swagger => スプリングフォックス

デフォルトの応答メッセージを上書きする

SpringfoxはデフォルトですべてのAPIコントローラに適用されるデフォルトの応答メッセージを定義します。これには、例えば201 - Createdと204 - No Content 、さらにいくつかの40x応答が含まれます。デフォルトの応答メッセージがAPIに適用されない場合があります。あなたはこれに対処する可能性を組み込む必要があります：

@ApiResponsesアノテーションを使用して、デフォルトの応答メッセージを有効にして独自のメッセージを定義することができます。
自分の応答メッセージをグローバルに定義することができます

デフォルトの応答メッセージのターン

docket.useDefaultResponseMessages(false);

個々の応答メッセージは、コントローラごとに設定できます。例えば

 @ApiResponses(value = {
        @ApiResponse(code=400, message = "This is a bad request, please stick to the API description", response = RestApiExceptionModel.class),
        @ApiResponse(code=401, message = "Your request cannot be authorized.", response = RestApiExceptionModel.class)
 })

独自のデフォルト応答メッセージを設定する

ModelRef errorModel = new ModelRef("RestApiExceptionModel");
List<ResponseMessage> responseMessages = Arrays.asList(
        new ResponseMessageBuilder().code(401).message("Unauthorized").responseModel(errorModel).build(),
        new ResponseMessageBuilder().code(403).message("Forbidden").responseModel(errorModel).build(),
        new ResponseMessageBuilder().code(404).message("NotFound").responseModel(errorModel).build());

docket.globalResponseMessage(RequestMethod.POST, responseMessages)
        .globalResponseMessage(RequestMethod.PUT, responseMessages)
        .globalResponseMessage(RequestMethod.GET, responseMessages)
        .globalResponseMessage(RequestMethod.DELETE, responseMessages);

spring-bootでswagger-uiを使用してspringfoxを設定する

MavenまたはGradleを使用してアプリケーションにspringfoxを取得する
アプリケーションで新しいDocket Beanを作成し、それを設定する
必要に応じてAPIを文書化する
アプリケーションを起動し、達成された結果を確認する

＃1 Mavenでspringfoxを取得する

pom.xmlにswagger2とswagger-uiの依存関係を追加する

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

＃2スワッガーを使用するようにアプリケーションを設定する

アノテーション@EnableSwagger2を@SpringBootApplicationアノテーション付きメインクラスに追加し、この（または他の）コンフィグレーションクラス内にスワッガーDocket Beanを作成します。

@Bean
public Docket api() {                
    return new Docket(DocumentationType.SWAGGER_2)          
      .select()                                       
      .apis(RequestHandlerSelectors.any())
      .paths(PathSelectors.any())                     
      .build();
}

この構成では、アプリケーション内のすべてのSpring Controller上でAPIドキュメントが生成されます。 APIドキュメントの生成を特定のコントローラに限定する必要がある場合は、さまざまなRequestHandlerSelectorの中から選択できます。たとえば、 RequestHandlerSelectors.basePackage("your.package.structure")を使用するRequestHandlerSelectors.withClassAnnotation(Api.class)を使用して注釈を付けた特定のクラスに基づいて、パッケージ構造に基づいてAPIドキュメントを生成できます。

＃3あなたのAPIを文書化する

マニュアルに記載されている注釈を使用して、コントローラのクラスとメソッドを追加情報で強化してください。一般的なタイトル、説明、バージョンなど、apiの一般的な情報を記述するには、Docket bean内のApiInfoBuilder（）を使用してください。

ApiInfoBuilderを使用したメタデータ定義の例：

// Within your configuration class
public static ApiInfo metadata(){
    return new ApiInfoBuilder()
            .title("Your Title")
            .description("Your Description")
            .version("1.x")
            .build();
}

// Within your method that definies the Docket bean...
docket.apiInfo(metadata());

Modified text is an extract of the original Stack Overflow Documentation

ライセンスを受けた CC BY-SA 3.0

所属していない Stack Overflow

swagger
スプリングフォックス

サーチ…