swagger
springfox

Standaard antwoordberichten overschrijven

Springfox definieert een ingestelde standaardreactieberichten die standaard op alle API-controllers worden toegepast. Dit omvat bijvoorbeeld 201 - Created en 204 - No Content , evenals verschillende 40x antwoorden. Er kunnen gevallen zijn waarin de standaardreactieberichten niet van toepassing zijn op uw API. Je moet ingebouwde mogelijkheden hebben om hiermee om te gaan:

• U kunt het standaardantwoordbericht uitschakelen en uw eigen antwoord definiëren met behulp van de annotatie @ApiResponses .
• U kunt uw eigen antwoordberichten wereldwijd definiëren

Schakel standaard antwoordberichten uit

docket.useDefaultResponseMessages(false);

U kunt nu uw individuele antwoordberichten instellen op het niveau van een controller. Eg

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

Stel uw eigen standaard antwoordberichten in

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

Springfox instellen met swagger-ui in spring-boot

1. Download Springfox in uw toepassing met Maven of Gradle
2. Maak een nieuwe Docket bean in uw toepassing en configureer deze
3. Documenteer uw API volgens uw behoeften
4. Start uw applicatie en bekijk uw behaalde resultaten

# 1 Springfox halen met Maven

Voeg de afhankelijkheden voor swagger2 en swagger-ui toe aan je 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 Configureer uw applicatie om swagger te gebruiken

Voeg de annotatie @EnableSwagger2 aan uw @SpringBootApplication geannoteerde hoofdklasse en maak een swagger Docket bean in deze (of een andere) configuratieklasse.

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

Deze configuratie genereert een API-documentatie over alle veercontrollers in uw toepassing. Als u het genereren van API-documentatie tot bepaalde controllers wilt beperken, kunt u kiezen tussen verschillende RequestHandlerSelectors. U kunt bijvoorbeeld uw API-documentatie genereren op basis van uw pakketstructuur met behulp van RequestHandlerSelectors.basePackage("your.package.structure") of op basis van specifieke klassen die u hebt geannoteerd met RequestHandlerSelectors.withClassAnnotation(Api.class) .

# 3 Documenteer uw API

Gebruik de annotaties zoals beschreven in de documentatie om uw controllerklassen en -methoden met aanvullende informatie te verbeteren. Gebruik de ApiInfoBuilder () in uw Docket bean om de algemene informatie van uw API te beschrijven, zoals de algemene titel, de beschrijving of de versie.

Voorbeeld voor de metagegevensdefinitie met 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());