はじめに
しばらく使っていたSpringFoxでアプリケーションが実行できなくなる問題が発生していたので、Springdocへ乗り換え。ついでにOpenAPI2.0->OpenAPI3.0へ移行したのでまとめる。
概要
Springdocを使ってSwagger.yamlを生成。これを経由してSwaggerCodegenでマークダウン形式のAPIドキュメントを作成する。APIクライアントも作成されると思うが、今回はドキュメントのみチェック。
やったこと
アプリケーションについて
SwaggercodegenApplication.java
@OpenAPIDefinition(
info = @Info(
title = "サンプルAPIのタイトルです",
version = "1.0",
description = "サンプルAPIの説明です",
license = @License(name = "ライセンス名", url = "https://qiita.com/Ikeponias"),
contact = @Contact(url = "https://qiita.com/Ikeponias", name = "Ikeponias", email = "Ikeponias@Ikeponias.com")),
tags = {},
externalDocs = @ExternalDocumentation(description = "外部ドキュメント"),
security = {},
servers = {
@Server(
description = "サーバ説明",
url = "https://qiita.com/Ikeponias",
variables = {})
})
@SpringBootApplication
public class SwaggercodegenApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggercodegenApplication.class, args);
}
}
SampleRestController.java
@RestController
@RequestMapping("sample")
public class SampleRestController {
@Operation(summary = "サンプルgetAPIの概要です",
tags = {},
security = {},
responses = {
@ApiResponse(
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = SampleResponse.class))),
@ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
@ApiResponse(responseCode = "404", description = "Pet not found"),
@ApiResponse(responseCode = "405", description = "Validation exception") }
)
@GetMapping
SampleResponse getResponse() {
return new SampleResponse(1, new UserResponse("Sample Name", "aaa@bbb.com"));
}
@Operation(summary = "サンプルpostAPIの概要です",
tags = {},
security = {},
responses = {
@ApiResponse(responseCode = "200",description = "200コードの説明"),
@ApiResponse(responseCode = "400", description = "400コードの説明"),
@ApiResponse(responseCode = "403", description = "403コードの説明"),
@ApiResponse(responseCode = "404", description = "404コードの説明")
})
@PostMapping
void postRequest(@RequestBody(
description = "リクエスト説明",
required = true,
content = @Content(schema = @Schema(implementation = SampleRequest.class))) SampleRequest sampleRequest) {
}
}
SampleRequest.java
@Value
public class SampleRequest {
@Schema(required = true, description = "idの説明", minimum = "1", maximum = "100")
Integer id;
@Schema(required = true, description = "userRequestの説明")
UserRequest userRequest;
}
SampleResponse.java
@Value
public class SampleResponse {
@Schema(description = "idの説明")
Integer id;
@Schema(description = "userResponseの説明")
UserResponse userResponse;
}
Springdocによるswagger.yaml生成
pom.xml の依存関係にSpringdocを追加。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.6.6</version>
</dependency>
あとはアプリケーションを実行する。
swagger-ui/index.html へアクセスすることで、↓のページを確認できる。OpenAPI3.0様式であることもわかる。
また、/v3/api-docs.yaml へアクセスすることで swagger.yaml をダウンロードできる。アクセスパスは設定で変更可能。
ただ、CI等で使う際は少々扱いづらいので、今回は単体テスト経由でダウンロードする。
今回はあのLINE様がこれに関する記事を出してくださっていたのでこれをパク…リスペクトした。
@Autowired
WebApplicationContext context;
@Test
public void generateOasFile() throws Exception {
MockMvc mockMvc = MockMvcBuilders.webAppContextSetup(context).build();
mockMvc.perform(MockMvcRequestBuilders.get("/v3/api-docs.yaml"))
.andDo(result -> FileUtils.write(
new File("swagger.yaml"),
new String(result.getResponse().getContentAsByteArray(), StandardCharsets.UTF_8),
StandardCharsets.UTF_8));
}
これでCIを導入していれば、単体テスト実行時に swagger.yaml が生成されている。
今回生成された swagger.yaml は以下。
openapi: 3.0.1
info:
title: サンプルAPIのタイトルです
description: サンプルAPIの説明です
contact:
name: Ikeponias
url: https://qiita.com/Ikeponias
email: Ikeponias@Ikeponias.com
license:
name: ライセンス名
url: https://qiita.com/Ikeponias
version: "1.0"
externalDocs:
description: 外部ドキュメント
servers:
- url: https://qiita.com/Ikeponias
description: サーバ説明
paths:
/sample:
get:
tags:
- sample-rest-controller
summary: サンプルgetAPIの概要です
operationId: getResponse
responses:
default:
description: default response
content:
application/json:
schema:
$ref: '#/components/schemas/SampleResponse'
"400":
description: Invalid ID supplied
content:
'*/*':
schema:
$ref: '#/components/schemas/SampleResponse'
"404":
description: Pet not found
content:
'*/*':
schema:
$ref: '#/components/schemas/SampleResponse'
"405":
description: Validation exception
content:
'*/*':
schema:
$ref: '#/components/schemas/SampleResponse'
post:
tags:
- sample-rest-controller
summary: サンプルpostAPIの概要です
operationId: postRequest
requestBody:
description: リクエスト説明
content:
application/json:
schema:
$ref: '#/components/schemas/SampleRequest'
required: true
responses:
"200":
description: 200コードの説明
"400":
description: 400コードの説明
"403":
description: 403コードの説明
"404":
description: 404コードの説明
components:
schemas:
SampleRequest:
required:
- id
- userRequest
type: object
properties:
id:
maximum: 100
minimum: 1
type: integer
description: idの説明
format: int32
userRequest:
$ref: '#/components/schemas/UserRequest'
UserRequest:
required:
- mail
type: object
properties:
name:
maxLength: 100
minLength: 1
type: string
description: nameの説明
mail:
maxLength: 50
minLength: 1
type: string
description: mailの説明
description: userRequestの説明
SampleResponse:
type: object
properties:
id:
type: integer
description: idの説明
format: int32
userResponse:
$ref: '#/components/schemas/UserResponse'
UserResponse:
type: object
properties:
name:
type: string
description: nameの説明
mail:
type: string
description: mailの説明
description: userResponseの説明
Swagger Codegenによるマークダウン形式のAPIドキュメント生成
Windowsの私は、今回OpenAPI3.0なので作業フォルダの中で以下のコマンドをPowerShellで実行。
wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.31/swagger-codegen-cli-3.0.31.jar -O swagger-codegen-cli.jar
手元に swagger-codegen-cli-jar がダウンロードできていることを確認する。
その後、以下のコマンドをPowerShellで実行。パスはよしなに変える。
しれっとテンプレートも変更しているが、これは別に書ければ書く…書ければ…書く
java -jar swagger-codegen-cli.jar generate -i swagger.yaml -l java -o generated -t templates
実行後、-i オプションで指定したswagger.yamlから -o オプションで指定したフォルダ(ここでは generated )が生成され、中にswagger関連のファイルがあることを確認する。
最後に出力されたフォルダ内の doc フォルダの中に md 拡張子のAPIドキュメントが作成されていればOK。
ちなみに今回作成したAPIエンドポイントとリクエストのドキュメントは以下。
あとはお好きにカスタマイズすると良いと思う。