swagger
springfox

Sostituisci i messaggi di risposta predefiniti

Springfox definisce un set di messaggi di risposta predefiniti che vengono applicati a tutti i controller API per impostazione predefinita. Questo include ad esempio 201 - Created e 204 - No Content , oltre a diverse risposte 40x . Potrebbero esserci casi in cui i messaggi di risposta predefiniti non si applicano alla tua API. Devi costruire possibilità per affrontare questo:

• È possibile disattivare il messaggio di risposta predefinito e definirne uno utilizzando l'annotazione @ApiResponses .
• Puoi definire i tuoi messaggi di risposta a livello globale

Disabilita i messaggi di risposta predefiniti

docket.useDefaultResponseMessages(false);

Ora puoi impostare i tuoi singoli messaggi di risposta a livello di controller. Per esempio

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

Imposta i tuoi messaggi di risposta predefiniti

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

Imposta springfox usando swagger-ui in spring-boot

1. Scarica Springfox nella tua applicazione utilizzando Maven o Gradle
2. Creare un nuovo bean Docket nell'applicazione e configurarlo
3. Documenta la tua API in base alle tue esigenze
4. Avvia la tua applicazione e guarda i risultati ottenuti

# 1 Ottenere springfox con Maven

Aggiungi le dipendenze per swagger2 e swagger-ui nel tuo 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 Configura la tua applicazione per usare lo swagger

Aggiungi l'annotazione @EnableSwagger2 alla classe principale annotata @SpringBootApplication e crea uno swagger Docket bean all'interno di questa (o qualsiasi altra) classe di configurazione.

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

Questa configurazione genererà una documentazione API su tutti i controller Spring della tua applicazione. Se è necessario limitare la generazione della documentazione API a determinati controller, è possibile scegliere tra vari RequestHandlerSelector. Ad esempio, è possibile generare la documentazione dell'API in base alla struttura del pacchetto utilizzando RequestHandlerSelectors.basePackage("your.package.structure") o le classi specifiche basate che sono state annotate utilizzando RequestHandlerSelectors.withClassAnnotation(Api.class) .

# 3 Documenta la tua API

Utilizzare le annotazioni come descritto nella documentazione , per migliorare le classi e i metodi del controller con informazioni aggiuntive. Per descrivere le informazioni generali della tua API, come il titolo generale, la descrizione o la versione, fai uso di ApiInfoBuilder () all'interno del tuo Docket bean.

Esempio per la definizione dei metadati utilizzando 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());