streamalism.org

1. Overzicht

Swagger is een set specificaties om REST API's te documenteren en te beschrijven. Het biedt ook voorbeeldwaarden voor de eindpuntparameters.

In deze zelfstudie laten we zien hoe u een standaardvoorbeeldwaarde maakt voor Draad arrays, aangezien dit gedrag niet standaard is ingeschakeld.

2. Specificeer een array van strings als Body Parameters in Swagger

Het probleem doet zich voor wanneer we een reeks strings willen specificeren als body-parameters in Swagger.

De standaard Voorbeeldwaarde van Swagger is een beetje ondoorzichtig, zoals we kunnen zien in de Swagger-editor:

Dus hier zien we dat Swagger niet echt een voorbeeld laat zien van hoe de array-inhoud eruit zou moeten zien. Laten we eens kijken hoe we er een kunnen toevoegen.

3. YAML

Ten eerste beginnen we met het specificeren van de reeks strings in Swagger met behulp van YAML-notatie. In het schema-gedeelte nemen we op type: array met items String.

Om de API beter te documenteren en de gebruiker te instrueren, kunnen we de voorbeeld label voor het invoegen van waarden:

parameters: - in: body beschrijving: "" vereist: waar naam: naam schema: type: array items: type: string voorbeeld: ["str1", "str2", "str3"]

Laten we eens kijken hoe ons display nu informatiever is:

4. Springfox

Of we kunnen hetzelfde resultaat bereiken met Springfox.

We moeten de data type en voorbeeld in het datamodel met @ApiModel en @ApiModelProperty annotaties:

@ApiModel openbare klasse Foo {lange privé-id; @ApiModelProperty (naam = "naam", dataType = "Lijst", voorbeeld = "[\" str1 \ ", \" str2 \ ", \" str3 \ "]") privélijstnaam;

Daarna moeten we ook de Controller om Swagger naar het datamodel te laten verwijzen.

Dus laten we gebruiken @ApiImplicitParams daarom:

@RequestMapping (method = RequestMethod.POST, value = "/ foos") @ResponseStatus (HttpStatus.CREATED) @ResponseBody @ApiImplicitParams ({@ApiImplicitParam (name = "foo", value = "Lijst met strings", paramType = "body ", dataType =" Foo ")}) openbare Foo create (@RequestBody final Foo foo) {

En dat is het!

5. Conclusie

Bij het documenteren van de REST API's kunnen we parameters hebben die string-arrays zijn. Idealiter documenteren we deze met voorbeeldwaarden.

We kunnen dit in Swagger doen met de voorbeeld eigendom. Of we kunnen de voorbeeld annotatie-attribuut in Springfox.

Zoals altijd is de code beschikbaar op GitHub.