swagger
Springfuchs

Standard-Antwortnachrichten überschreiben

Springfox definiert einen Satz von Standardantwortnachrichten, die standardmäßig auf alle API-Controller angewendet werden. Dazu gehören zB 201 - Created und 204 - No Content sowie mehrere 40x Antworten. Es kann Fälle geben, in denen die Standardantwortnachrichten für Ihre API nicht zutreffen. Sie müssen eingebaute Möglichkeiten haben, um damit umzugehen:

• Sie können die Standardantwortnachricht @ApiResponses und mithilfe der Annotation @ApiResponses Ihre eigene definieren.
• Sie können Ihre eigenen Antwortnachrichten global definieren

Standard-Antwortnachrichten abschalten

docket.useDefaultResponseMessages(false);

Sie können jetzt Ihre individuellen Antwortnachrichten auf Controller-Ebene einstellen. Z.B

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

Legen Sie Ihre eigenen Standardantwortnachrichten fest

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 mit Swagger-Ui im Springboot einrichten

1. Holen Sie sich Springfox in Ihre Anwendung, indem Sie Maven oder Gradle verwenden
2. Erstellen Sie eine neue Docket-Bean in Ihrer Anwendung und konfigurieren Sie sie
3. Dokumentieren Sie Ihre API entsprechend Ihren Anforderungen
4. Starten Sie Ihre Bewerbung und sehen Sie Ihre erzielten Ergebnisse

# 1 Springfuchs mit Maven bekommen

Fügen Sie die Abhängigkeiten für swagger2 und swagger-ui in Ihrer pom.xml hinzu

<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 Konfigurieren Sie Ihre Anwendung für die Verwendung von Swagger

Fügen Sie der Annotation- @EnableSwagger2 @SpringBootApplication die Annotation @EnableSwagger2 , und erstellen Sie eine Swagger-Docket-Bean innerhalb dieser (oder einer anderen) Konfigurationsklasse.

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

Diese Konfiguration generiert eine API-Dokumentation über alle Federsteuerungen in Ihrer Anwendung. Wenn Sie die Generierung der API-Dokumentation auf bestimmte Controller beschränken müssen, können Sie zwischen verschiedenen RequestHandlerSelectors wählen. Sie können beispielsweise Ihre API-Dokumentation basierend auf Ihrer RequestHandlerSelectors.basePackage("your.package.structure") mit RequestHandlerSelectors.basePackage("your.package.structure") oder basierend auf bestimmten Klassen RequestHandlerSelectors.withClassAnnotation(Api.class) , die Sie mit RequestHandlerSelectors.withClassAnnotation(Api.class) kommentiert haben.

# 3 Dokumentieren Sie Ihre API

Verwenden Sie die Anmerkungen wie in der Dokumentation beschrieben , um Ihre Steuerungsklassen und -methoden um zusätzliche Informationen zu erweitern. Um die allgemeinen Informationen zu Ihrer API, wie den allgemeinen Titel, die Beschreibung oder die Version, zu beschreiben, verwenden Sie den ApiInfoBuilder () in Ihrer Docket-Bean.

Beispiel für die Metadaten-Definition mit 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());