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でそのモジュールを確認してください。