SpringBoot（5）-Swagger2を統合してAPIドキュメントを構築する

私たちの仕事では、いくつかのAPIを開発するとき、通常、完了後に対応するインターフェイスドキュメントを提供する必要があるため、インターフェイスドキュメントの番号付けを完了して書き込むために、一定の時間と労力を費やす必要がありますインターフェースドキュメントでは、要件の変更とプロジェクトの最適化と進歩に伴って、インターフェースの詳細が常に進化しており、インターフェースの説明ドキュメントも同期的に修正する必要があります。これは非常に面倒なので、自動ドキュメント生成モード（swagger2、RAPなど）を採用できます。。

ここでは、主にSwagger2の基本的な使用法を紹介します。Swagger2は、プロジェクトで強力なRESTful APIドキュメントを自動的に生成して、ワークロードを削減できます。APIドキュメントは、API記述の同時更新を容易にするコードと統合されており、それぞれをデバッグするページテスト機能を提供しますRESTful API。

まず、Swagger2を使用する場合、最初に行う必要があるのは、次のように関連する依存関係を導入することです。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

次に、次のようにSwagger2構成クラスを追加する必要があります。

@Configuration
@EnableSwagger2
public class Swagger2Config {

    //api接口包扫描路径
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.kimi";
    //api接口文档版本信息
    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为指定包下Controller生成API文档
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any())
                .build();
    }

    //创建api的基本信息
    private ApiInfo apiInfo() {
        Contact contact = new Contact("Kimi", "www.kimi0107.com", "[email protected]");
        return new ApiInfoBuilder()
                //设置文档的标题
                .title("集成Swagger2构建API文档")
                //设置文档的描述
                .description("SpringBoot集成Swagger2构建restful API文档")
                //设置文档的License信息
                .termsOfServiceUrl("http://www.kimi0107.com/")
                //设置文档的联系信息
                .contact(contact)
                //设置文档的版本信息
                .version(VERSION)
                .build();
    }
}

上記のコードに示すように、@Configurationアノテーションを使用して、Springに構成クラスをロードさせます。@EnableSwagger2注釈を使用してSwagger2を有効にします。メンバーメソッドcreateRestApi関数がDocket Beanを作成した後、apiInfo（）を使用してAPIの基本情報を作成します（これらの基本情報はドキュメントページに表示されます）。

select（）関数は、ApiSelectorBuilderインスタンスを返し、表示するSwaggerに公開されるインターフェイスを制御します。この例では、指定されたスキャンパッケージパスを使用して定義します。Swaggerは、パッケージの下でコントローラーによって定義されたすべてのAPIをスキャンし、ドキュメントコンテンツを生成します（@ApiIgnore指定されたものを除く）リクエスト）。

もちろん、指定されたスキャンパッケージパスを処理して、インターフェイスドキュメントを生成するインターフェイスを定義しますが、他の方法もあります。一般的な方法は次のとおりです。
ここに画像の説明を挿入

上記の設定を完了すると、実際にドキュメントのコンテンツを生成できますが、そのようなドキュメントは主にリクエスト自体のためのものであり、説明は主に関数の命名などから派生しており、ユーザーにとって使いにくいものであり、プロジェクトを開始し、アクセスしますhttp：// localhost：8080 / swagger-ui.html、インターフェースは次のとおりです。
ここに画像の説明を挿入

上のスクリーンショットから参照してくださいどこ我々が直接テストすることができ、インターフェースは、すでに非常に強いですが、実際の使用では、我々はまた、文書の内容を豊かにするためにいくつかのメモを追加するために、比較的多くの共通所有することができます@ApiOperationし、@ApiImplicitParam2つの音符を、次のように：
ここに画像の説明を挿入

さらに、メソッドに複数のパラメーターが含まれている場合、@ApiImplicitParams代わり@ApiImplicitParamにそれを使用でき、その使用法は非常に簡単です。つまり、複数の@ApiImplicitParam配列を含むことができるパラメーターです。
ここに画像の説明を挿入

しかし、時には私たちはしばしば、我々が使用する必要があり、ここで、引数を渡すために、エンティティクラスに使用@ApiModelし、@ApiModelProperty次のように、エンティティクラスへの使用に、注釈付きの指示に：
ここに画像の説明を挿入

次のように、私たちが仕事でよく使用するメモもあります。

@Api

@Api（tags = ""このクラスの役割を説明してください "、value =" "パラメータは無意味です。通常は設定しないでください"）

クラス全体を装飾し、要求されたクラスに配置します。@ Controllerと並べて、ユーザーモジュールAPI、注文モジュールAPIなどのクラスの役割を説明します。
ここに画像の説明を挿入

@ApiOperation

@ApiOperation（value = ""メソッドの役割を説明してください "、notes =" "メソッドの備考"）

@ApiImplicitParams、@ ApiImplicitParam

@ApiImplicitParam：
@ApiImplicitParams：リクエストのメソッドで使用される単一のパラメータの説明には、一連のパラメータの説明が含まれています

@ApiImplicitParams（{
@ApiImplicitParam（name =“ id”、value =“ user ID”、required = true、paramType =“ form”）、
@ApiImplicitParam（name =“ name”、value =“ user name”、required = true 、ParamType =“ form”）、
@ ApiImplicitParam（name =“ age”、value =“ user age”、required = true、paramType =“ form”、dataType =“ Integer”）
}）

name：パラメータname
value：parameter
必要な漢字の説明と説明：パラメータを渡す必要があるかどうか
paramType：パラメータヘッダーを配置する場所-
>リクエストパラメータの取得：@RequestHeaderクエリ-
>リクエストパラメータの取得：@RequestParam
パス（レストフルインターフェイス用）->リクエストパラメータGet：@PathVariable
body（Request body）–> @RequestBody User user
form（general form submission）
dataType：parameter type、default String、other values dataType =“ int”
defaultValue：default value of parameter

@ApiResponses、@ ApiResponse

@ApiResponses：メソッドは、オブジェクトの説明戻り
@ApiResponse：、各パラメータの説明を

@ApiResponses（{
@ApiResponse（コード= 400、メッセージ= "リクエストパラメータが
入力されていません"）、@ApiResponse（コード= 404、メッセージ= "リクエストパスが見つかりませんでした"）
}）

コード：番号、たとえば400
メッセージ：メッセージ、たとえば「リクエストパラメータが入力されていません」
レスポンス：例外をスローするクラス

@ApiIgnore

アノテーションを使用してこのAPIを無視し、ドキュメント生成に参加しない

@ApiError

エラー発生時に返される情報

@ApiProperty

オブジェクトでパラメーターを受け取る場合、オブジェクトのフィールドを記述します

Swagger2ビルドAPIドキュメントを統合した後は、テスト環境でのみ使用する必要があるかもしれませんが、生成環境では閉じる必要があります。ここで、Spring Bootで関連する構成を構成できます。：

swagger.enable=true

swagger:
  enable: true

ここに画像の説明を挿入

さらに、Spring Securityをプロジェクトに統合するか、Shiroと他の権限制御を統合すると、追加の設定なしでSwagger2ドキュメントが傍受されます。解決策は、関連する構成クラスにホワイトリストを追加することです。

たとえば、セキュリティ構成クラスの構成メソッドをオーバーライドできます。

@Override
public void configure (WebSecurity web) throws Exception {
    web.ignoring()
      .antMatchers("/swagger-ui.html")
      .antMatchers("/v2/**")
      .antMatchers("/swagger-resources/**");
}

または、次のようにShiroの構成クラスの関連構成として：

//swagger2免拦截
filterChainDefinitionMap.put("/swagger-ui.html**", "anon");
filterChainDefinitionMap.put("/v2/api-docs", "anon");
filterChainDefinitionMap.put("/swagger-resources/**", "anon");
filterChainDefinitionMap.put("/webjars/**", "anon");

継承されたWebMvcConfigurationSupport、addResourceHandlersメソッドを書き換え

/**
 * 配置swagger2的静态资源路径
 */
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 解决静态资源无法访问
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/static/");
    // 解决swagger无法访问
    registry.addResourceHandler("/swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    // 解决swagger的js文件无法访问
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

kimi_0107

286の元の記事が公開されました・ Liked12 ・訪問者10,000以上

プライベートの手紙の懸念