Geben Sie in Swagger ein Array von Zeichenfolgen als Körperparameter an

1. Übersicht

Swagger ist eine Reihe von Spezifikationen zur Dokumentation und Beschreibung von REST-APIs. Es enthält auch Beispielwerte für die Endpunktparameter.

In diesem Lernprogramm wird gezeigt, wie ein Standardbeispielwert für String- Arrays erstellt wird, da dieses Verhalten standardmäßig nicht aktiviert ist.

2. Geben Sie in Swagger ein Array von Zeichenfolgen als Körperparameter an

Das Problem tritt auf, wenn wir in Swagger ein Array von Zeichenfolgen als Body-Parameter angeben möchten.

Der Standard-Beispielwert von Swagger ist etwas undurchsichtig, wie wir im Swagger-Editor sehen können:

Hier sehen wir also, dass Swagger nicht wirklich ein Beispiel dafür zeigt, wie der Array-Inhalt aussehen sollte. Mal sehen, wie man einen hinzufügt.

3. YAML

Zunächst geben wir das Array der Zeichenfolgen in Swagger in YAML-Notation an. Im Schemaabschnitt enthalten wir type: array with items String .

Um die API besser zu dokumentieren und den Benutzer zu instruieren, können wir die Beispielbezeichnung zum Einfügen von Werten verwenden:

parameters: - in: body description: "" required: true name: name schema: type: array items: type: string example: ["str1", "str2", "str3"]

Mal sehen, wie unser Display jetzt informativer ist:

4. Springfox

Oder wir können mit Springfox das gleiche Ergebnis erzielen.

Wir müssen die verwenden datatype und Beispiel im Datenmodell mit @ApiModel und @ApiModelProperty Anmerkungen:

@ApiModel public class Foo { private long id; @ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]") private List name;

Danach müssen wir auch den Controller mit Anmerkungen versehen , damit Swagger auf das Datenmodell zeigt.

Verwenden wir also @ApiImplicitParams dafür:

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

Und das ist es!

5. Schlussfolgerung

Bei der Dokumentation der REST-APIs haben wir möglicherweise Parameter, die Zeichenfolgenarrays sind. Idealerweise dokumentieren wir diese mit Beispielwerten.

Wir können dies in Swagger mit der Beispiel- Eigenschaft tun . Oder wir können das Beispielanmerkungsattribut in Springfox verwenden.

Wie immer ist der Code auf GitHub verfügbar.