swagger
springfox

Zastąp domyślne wiadomości odpowiedzi

Springfox definiuje zestaw domyślnych komunikatów odpowiedzi, które są domyślnie stosowane do wszystkich kontrolerów API. Obejmuje to np. 201 - Created i 204 - No Content , a także kilka odpowiedzi 40x . Mogą zdarzyć się przypadki, w których domyślne odpowiedzi nie mają zastosowania do Twojego interfejsu API. Musisz poradzić sobie z tym:

• Możesz wyłączyć domyślny komunikat odpowiedzi i zdefiniować własny, korzystając z adnotacji @ApiResponses .
• Możesz zdefiniować własne komunikaty odpowiedzi globalnie

Włączanie domyślnych komunikatów odpowiedzi

docket.useDefaultResponseMessages(false);

Możesz teraz ustawić swoje indywidualne odpowiedzi na poziomie kontrolera. Na przykład

 @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)
 })

Ustaw własne domyślne wiadomości odpowiedzi

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);

Skonfiguruj springfox za pomocą swagger-ui w spring-boot

1. Pobierz springfox do swojej aplikacji za pomocą Maven lub Gradle
2. Utwórz nową fasolę Docket w swojej aplikacji i skonfiguruj ją
3. Udokumentuj swój interfejs API zgodnie z potrzebami
4. Uruchom aplikację i zobacz osiągnięte wyniki

# 1 Zdobycie springfox z Maven

Dodaj zależności do swagger2 i swagger-ui w pliku pom.xml

<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 Skonfiguruj aplikację tak, aby używała narzędzia swagger

Dodaj adnotację @EnableSwagger2 do swojej głównej klasy @SpringBootApplication adnotacjami i utwórz fasolę Docket swagger w tej (lub dowolnej innej) klasie konfiguracyjnej.

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

Ta konfiguracja wygeneruje dokumentację API na wszystkich kontrolerach sprężyn w Twojej aplikacji. Jeśli chcesz ograniczyć generowanie dokumentacji API do niektórych kontrolerów, możesz wybierać między różnymi RequestHandlerSelectors. Np. Możesz wygenerować dokumentację API na podstawie struktury pakietu za pomocą RequestHandlerSelectors.basePackage("your.package.structure") lub na podstawie określonych klas, które RequestHandlerSelectors.withClassAnnotation(Api.class) adnotacji za pomocą RequestHandlerSelectors.withClassAnnotation(Api.class) .

# 3 Udokumentuj swój interfejs API

Użyj adnotacji zgodnie z opisem w dokumentacji , aby ulepszyć klasy i metody kontrolera o dodatkowe informacje. Aby opisać ogólne informacje o interfejsie API, takie jak ogólny tytuł, opis lub wersja, skorzystaj z ApiInfoBuilder () w komponencie bean Docket.

Przykład definicji metadanych przy użyciu 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());