swagger
springfox
Szukaj…
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
- Pobierz springfox do swojej aplikacji za pomocą Maven lub Gradle
- Utwórz nową fasolę Docket w swojej aplikacji i skonfiguruj ją
- Udokumentuj swój interfejs API zgodnie z potrzebami
- 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());