web-dev-qa-db-fra.com

Utilisez @ApiParam ou @ApiModelProperty dans swagger?

Les deux annotations suivantes fonctionnent pour ajouter des métadonnées aux documents swagger-ui. Laquelle devrait être préférée et pourquoi?

public class MyReq {

    @ApiModelProperty(required = true, value = "the persons name")
    @ApiParam(required = true, value = "the persons name")
    private String name;
}

@RestController
public class MyServlet {
   @RequestMapping("/") 
   public void test(MyReq req) {

   }
}
javaswaggerswagger-uiswagger-2.0
10
membersound

Il y a une énorme différence entre les deux. Ils sont tous deux utilisés pour ajouter des métadonnées à swagger mais ils ajoutent des métadonnées différentes.

@ApiParam est pour les paramètres. Il est généralement défini dans la classe de demande de ressource API.

Exemple de @ApiParam:

/users?age=50

il peut être utilisé pour définir l'âge des paramètres et les champs suivants:

  • paramType: requête
  • nom Age
  • description: âge de l'utilisateur
  • requis: vrai

@ApiModelProperty est utilisé pour ajouter des propriétés aux modèles. Vous l'utiliserez dans votre classe de modèle sur les propriétés du modèle.

Exemple:

l'utilisateur du modèle a le nom et l'âge comme propriétés: nom et âge, puis pour chaque propriété, vous pouvez définir les éléments suivants:

Pour l'âge:

  • type: entier,
  • format ": int64,
  • description: âge de l'utilisateur,

Consultez les champs que chacun dénote dans les objets swagger:

@ ApiModelProperty- https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#529-property-object

@ApiParam - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/1.2.md#524-parameter-object

14
slal