Swagger@Apiの説明は非推奨です
1. 概要
RESTful APIの説明は、ドキュメントで重要な役割を果たします。 REST APIの文書化に使用される一般的なツールの1つは、 Swagger2です。 ただし、説明の追加に使用される1つの便利な属性は廃止されました。 このチュートリアルでは、Swagger2とOpenAPI 3 を使用して、非推奨の description 属性の解決策を見つけ、これらを使用して[を説明する方法を示します。 X181X] RESTAPIアプリケーション。
2. APIの説明
デフォルトでは、SwaggerはRESTAPIクラス名の空の説明を生成します。 したがって、RESTAPIを記述するための適切なアノテーションを指定する必要があります。 Swagger2と@Apiアノテーションを使用するか、OpenAPI3で@Tagアノテーションを使用できます。
3. Swagger 2
Spring Boot RESTAPIにSwagger2を使用するには、Springfoxライブラリを使用できます。 pom.xmlファイルにspringfox-boot-starter依存関係を追加する必要があります。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Springfoxライブラリは、クラスをSwaggerリソースとして構成するための@Apiアノテーションを提供します。 以前は、 @Api アノテーションは、APIドキュメントをカスタマイズするためのdescription属性を提供していました。
@Api(value = "", description = "")
ただし、前述のように、description属性は非推奨です。 幸いなことに、別の方法があります。 タグ属性を使用できます。
@Api(value = "", tags = {"tag_name"})
Swagger 1.5では、タグを定義するために@SwaggerDefinitionアノテーションを使用します。 ただし、Swagger2ではサポートされなくなりました。 したがって、Swagger 2では、DocketBeanでtagsおよびdescriptionsを定義します。
@Configuration
public class SwaggerConfiguration {
public static final String BOOK_TAG = "book service";
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.tags(new Tag(BOOK_TAG, "the book API with description api tag"));
}
}
ここでは、タグを作成するために、 DocketbeanのTagクラスを使用しています。 これで、コントローラーでタグを参照できます。
@RestController
@RequestMapping("/api/book")
@Api(tags = {SwaggerConfiguration.BOOK_TAG})
public class BookController {
@GetMapping("/")
public List<String> getBooks() {
return Arrays.asList("book1", "book2");
}
}
4. OpenAPI 3
OpenAPI 3は、OpenAPI仕様の最新バージョンです。OpenAPI 2(Swagger 2)の後継です。 OpenAPI 3を使用してAPIを記述するために、@Tagアノテーションを使用できます。 さらに、 @Tag アノテーションは、descriptionと外部リンクを提供します。 BookControllerクラスを定義しましょう。
@RestController
@RequestMapping("/api/book")
@Tag(name = "book service", description = "the book API with description tag annotation")
public class BookController {
@GetMapping("/")
public List<String> getBooks() {
return Arrays.asList("book1", "book2");
}
}
5. 結論
この簡単な記事では、SpringBootアプリケーションのRESTAPIに説明を追加する方法について説明しました。 Swagger2とOpenAPI3を使用してこれを実現する方法を検討しました。 Swaggerセクションの場合、コードはGitHubでから入手できます。 OpenAPI 3のサンプルコードを確認するには、GitHubでそのモジュールを確認してください。