SpringBootプロジェクトでのSwagger2の使い方とアノテーション解説

1. Swagger 座標の依存関係をインポートします

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

最も一般的に使用されるバージョンは 2.9.2

2. スプリングにアノテーションを追加しますスタートアップクラス @ EnableSwagger2

springfox によって提供される @EnableSwagger2 アノテーションにより、swagger2 関連テクノロジーを有効にすることができます。プログラムは、現在のクラスのパッケージとそのサブパッケージ内のすべての型を走査して、Swagger に関連する注釈を検索し、Swagger ドキュメントをカスタマイズします

3. プロジェクトを開始して、swaggerui.html インターフェイスを表示します

「試してみる」をクリックして対応するパラメータを入力し、返された結果を表示します

4 番目に、SwaggerConfig 構成ファイルを作成します。

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Autowired
    private ApplicationContext applicationContext;

    private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

    @Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("平台接口 v1.0")
                .description("平台接口")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

@Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

Docker タイプのオブジェクトを作成し、Spring コンテナー管理を使用します。 Docker は Swagger のグローバル設定オブジェクトです。

使用するバージョンを決定するには、DocumentationType.SWAGGER_2 を使用して Docket のクラス オブジェクトを指定します。

apiInfo(): API ドキュメントの説明情報、パラメータは 1 つの ApiInfo クラス オブジェクトであり、bulid() ビルダーを使用して

private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("平台接口 v1.0")
               .description("平台接口")
               .contact(contact)
               .version("1.0")
               .build();
   }

contact() を作成します: クラス オブジェクトでもある Swagger ドキュメントのメイン コンテンツを構成します。 発行者名、ドキュメント発行者の Web サイト URL アドレス (企業 Web サイト)、ドキュメント発行者の電子メール アドレス

private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

title(): タイトル description(): 説明 information.version(): の 3 つのパラメータに設定します。バージョン情報

は次の内容に対応します

ApiSelectorBuilder を返すメソッドは select() で、これは Docker でセレクターを取得するために使用されます。 。ビルドセレクター。たとえば、どのパッケージの注釈をスキャンする必要があるか

apis(): 続いて、RequestHandlerSelectors クラスの (Predicate) ルールが続き、スキャンされるパッケージの注釈を規定します。デフォルトは、スタートアップ クラスとそのサブパッケージ

RequestHandlerSelectors クラスにはいくつかの静的メソッドがあります (3 つの例)

basePackage(): 後でパッケージ名の特定のアドレスを入力します。変更されたパッケージとそのサブパッケージのアノテーションがスキャンされます

docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))

any(): 任意のインターフェイスの API ドキュメントを生成します

none(): どのインターフェイスのインターフェイス ドキュメントも生成しません

path(): 正規表現を使用し、制約を生成します。API ドキュメントのパス アドレスと、その後にフィルター処理された (渡された) パスが続きます。

//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*页面或者admin路径下的所有页面都支持（or任意满足起一就通过）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

5: Swagger はカスタムをサポートします。アノテーション

はここでは言及されていません。興味があれば自分で検索できます (場所を残しておきます。後で使用します)

6: Swagger2 の共通アノテーション

@Api (一般的に使用されます)

関数 : @Api はクラスです。注意してください。クラス全体によって生成されるインターフェース情報の内容を制御します。

Attributes:

tags: クラスの名前。複数の値がある場合、つまり使用可能なコピー (エイリアス) が複数ある場合、SwaggerUI ビューには、どのコントローラーがメニューにアクセスできるかが表示されます。

#@ApiOperation

Function

: @ApiOperation はメソッドのアノテーションであり、関連するメソッドを説明します。メソッドの情報

#Attributes：

value：メソッドの説明 function

notes：メソッドのメモ (説明を展開)

@ApiParm

関数

: @ApiParmメソッドパラメータのアノテーションです。パラメータの説明

属性:

name:パラメータ名

value:パラメータの機能の説明

必須:値はブール型で、パラメータが必要なパラメータかどうかを示します。デフォルトは false

です。

@ApiIgnore

作用：@ApiParm是方法或者参数的注解。忽略注解的方法或者参数，不生成帮助文档

@ApiImplicitParam(常用)

作用：@ApiParm是作用于类上方法，用来描述方法参数的注解。

属性：

name：参数名称，和方法的参数一致

value：参数具体描述

required：值为boolean类型，表示该参数是否为必要参数，默认为false

paramType：参数类型

paramType="字符串"
paramType = "header"

dataType：数据类型

dataType = "string"  //字符串数据
dataType = "键值对"

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多个参数的描述

@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

@ApiModel(常用)

作用：@ApiModel是作用于实体类上，描述一个实体类型，整个实体类型如果成为任何一个生成api帮助文档的返回对象的时候，该注解被解析

属性：

value：实体类名称

description：实体类描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于实体类的属性上，描述实体类属性

属性：

value：实体属性描述

name：实体类属性名字，与属性名一致

以上がSpringBootプロジェクトでのSwagger2の使い方とアノテーション解説の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。