Swagger @ApiParam vs @ApiModelProperty

Java Top

Ich habe gerade den neuen Learn Spring- Kurs angekündigt , der sich auf die Grundlagen von Spring 5 und Spring Boot 2 konzentriert:

>> Überprüfen Sie den Kurs

1. Übersicht

In diesem Tutorial werden wir uns kurz die @ ApiParam- und @ ApiModelProperty- Annotationen von Swagger ansehen . Darüber hinaus werden wir diese Anmerkungen vergleichen und für jede die richtige Verwendung ermitteln.

2. Hauptunterschied

Einfach ausgedrückt , fügen die Anmerkungen @ApiParam und @ApiModelProperty Swagger verschiedene Metadaten hinzu. Die Annotation @ApiParam bezieht sich auf die Parameter einer API-Ressourcenanforderung, während sich @ApiModelProperty auf Eigenschaften des Modells bezieht .

3. @ApiParam

Die Annotation @ApiParam ist ausschließlich für die Annotationen von JAX-RS 1.x / 2.x-Parametern wie @PathParam , @QueryParam , @HeaderParam , @FormParam und @BeanParam vorgesehen . Obwohl swagger-core diese Anmerkungen standardmäßig scannt, können wir @ApiParam verwenden , um weitere Details zu den Parametern hinzuzufügen oder die Werte zu ändern, wenn sie aus dem Code gelesen werden.

Mit der Annotation @ApiParam können Sie den Namen, den Typ, die Beschreibung (den Wert) und den Beispielwert des Parameters angeben. Darüber hinaus können wir angeben, ob der Parameter erforderlich oder optional ist.

Schauen wir uns seine Verwendung an:

@RequestMapping( method = RequestMethod.POST, value = "/createUser", produces = "application/json; charset=UTF-8") @ResponseStatus(HttpStatus.CREATED) @ResponseBody @ApiOperation(value = "Create user", notes = "This method creates a new user") public User createUser( @ApiParam( name = "firstName", type = "String", value = "First Name of the user", example = "Vatsal", required = true) @RequestParam String firstName) { User user = new User(firstName); return user; }

Schauen wir uns die Darstellung der Swagger-Benutzeroberfläche für unser @ ApiParam- Beispiel an:

Schauen wir uns nun @ApiModelProperty an .

4. @ApiModelProperty

Mit der Annotation @ApiModelProperty können wir Swagger-spezifische Definitionen wie Beschreibung (Wert), Name, Datentyp, Beispielwerte und zulässige Werte für die Modelleigenschaften steuern.

Außerdem bietet es zusätzliche Filtereigenschaften, falls wir die Eigenschaft in bestimmten Szenarien ausblenden möchten.

Fügen wir dem Feld firstName des Benutzers einige Modelleigenschaften hinzu :

@ApiModelProperty( value = "first name of the user", name = "firstName", dataType = "String", example = "Vatsal") String firstName;

Schauen wir uns nun die Spezifikationen des Benutzermodells in der Swagger-Benutzeroberfläche an:

5. Schlussfolgerung

In diesem kurzen Artikel haben wir uns zwei Swagger-Annotationen angesehen, mit denen wir Metadaten für Parameter und Modelleigenschaften hinzufügen können. Dann haben wir uns einen Beispielcode mit diesen Anmerkungen angesehen und ihre Darstellungen in der Swagger-Benutzeroberfläche gesehen.

Wie immer sind alle diese Codebeispiele auf GitHub verfügbar.

Java unten

Ich habe gerade den neuen Learn Spring- Kurs angekündigt , der sich auf die Grundlagen von Spring 5 und Spring Boot 2 konzentriert:

>> Überprüfen Sie den Kurs