swagger
springfox
Sök…
Åsidosätta standard svar meddelanden
Springfox definierar ett inställt standardsvarmeddelanden som används på alla API-kontroller som standard. Detta inkluderar t.ex. 201 - Created
och 204 - No Content
, samt flera 40x
svar. Det kan förekomma fall där standardsvarsmeddelanden inte gäller för ditt API. Du måste bygga in möjligheter för att hantera detta:
- Du kan aktivera standardsvarsmeddelandet och definiera ditt eget med anteckningen
@ApiResponses
. - Du kan definiera dina egna svarmeddelanden globalt
Vrid på standardsvarsmeddelanden
docket.useDefaultResponseMessages(false);
Du kan nu ställa in dina individuella svarsmeddelanden på en kontroller-nivå. T.ex
@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)
})
Ställ in dina egna standardsvarmeddelanden
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);
Ställ in springfox med swagger-ui i spring-boot
- Få springfox till din applikation med Maven eller Gradle
- Skapa en ny Docket-böna i din applikation och konfigurera den
- Dokumentera ditt API enligt dina behov
- Starta din ansökan och se dina uppnådda resultat
# 1 Skaffa springfox med Maven
Lägg till beroenden för swagger2 och swagger-ui i din 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 Konfigurera din applikation för att använda swagger
Lägg till anteckningen @EnableSwagger2
i din @SpringBootApplication
kommenterade huvudklass och skapa en swagger Docket-böna i denna (eller någon annan) konfigurationsklass.
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
Denna konfiguration genererar en API-dokumentation över alla vårkontroller i din applikation. Om du behöver begränsa API-dokumentationsgenerationen till vissa kontroller kan du välja mellan olika RequestHandlerSelectors. Du kan t.ex. skapa din API-dokumentation baserad på din RequestHandlerSelectors.basePackage("your.package.structure")
med RequestHandlerSelectors.basePackage("your.package.structure")
eller baserade specifika klasser som du har kommenterat med RequestHandlerSelectors.withClassAnnotation(Api.class)
.
# 3 Dokumentera ditt API
Använd anteckningarna som beskrivs i dokumentationen för att förbättra dina kontrollklasser och metoder med ytterligare information. För att beskriva den allmänna informationen om din api, som allmän titel, beskrivning eller version, använd ApiInfoBuilder () i din Docket-böna.
Exempel för metadatadefinition med 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());