Andreas Bruns

Softwareentwicklung für Oldenburg und Bremen

Schnittstellen-Dokumentation mit Swagger

Bei der Erstellung von Schnittstellen (API: Application Programming Interface) für externe Systeme stellt sich meistens die Frage, wie die Schnittstellen dokumentiert werden sollen. Für REST-Schnittstellen hat Swagger die Dokumentation maßgeblich geprägt, sodass sich mittlerweise aus der ursprünglichen Swagger-Specification die OpenAPI-Specification (Github) in der Version 3 entwickelt hat. Eine Schnittstellen-Spezifikation (z.B. YAML-Datei) lässt sich auf zwei Arten konzipieren:

  • Contract/API First: Spezifikation wird mit Werkzeug oder manuell erzeugt
  • Code First: Schnittstelle wird programmiert und daraus Spezifikation generiert

Swagger bietet eine Reihe von lokalen und cloud-basierten Werkzeugen zur Erzeugung und Bereitstellung von Schnittsstellen-Dokumentationen:

  • Swagger UI: Dokumentation und REST-Interaktion für Schnittstellen-Konsumenten
  • Swagger Editor: Schnittstellen-Dokumentation erstellen und bearbeiten
  • Swagger Codegen: Generierung von Code aus Schnittstellen-Dokumentation
  • Swagger Inspector: Online-Werkzeug zum Testen von APIs
  • SwaggerHub: Software as a Service, das die Swagger-Werkzeuge (Codegen, Editor, UI) vereinigt

Hier ein paar Beispiele für die lokal einsetzbaren Swagger-Werkzeuge:

Swagger UI

  • Dokumentation und REST-Interaktion für Schnittstellen-Konsumenten
  • Online-Beispiel: https://petstore.swagger.io/
  • Integration in den eigenen Web-Server möglich (z.B. in Java per Springfox)

Swagger UI

Swagger Editor

Swagger Editor

Swagger Codegen

  • Generierung von Code aus Schnittstellen-Dokumentation
  • unterstützt viele Programmiersprachen, z.B.: Java, Scala, PHP, Go
  • Stub-Klassen für Java generieren:
    docker run --rm -v ${PWD}:/local swaggerapi/swagger-codegen-cli generate \
        -i http://petstore.swagger.io/v2/swagger.json \
        -l java \
        -o /local/stubs-java
    
  • generierte Stub-Klassen in Java für Maven-, Gradle- und SBT-Projekt:

    ➜  stubs-java$ tree
    .
    ├── README.md
    ├── build.gradle
    ├── build.sbt
    ├── docs
    │   ├── Category.md
    │   ├── ModelApiResponse.md
    │   ├── Order.md
    │   ├── Pet.md
    │   ├── PetApi.md
    │   ├── StoreApi.md
    │   ├── Tag.md
    │   ├── User.md
    │   └── UserApi.md
    ├── git_push.sh
    ├── gradle
    │   └── wrapper
    │       ├── gradle-wrapper.jar
    │       └── gradle-wrapper.properties
    ├── gradle.properties
    ├── gradlew
    ├── gradlew.bat
    ├── pom.xml
    ├── settings.gradle
    └── src
        ├── main
        │   ├── AndroidManifest.xml
        │   └── java
        │       └── io
        │           └── swagger
        │               └── client
        │                   ├── ApiCallback.java
        │                   ├── ApiClient.java
        │                   ├── ApiException.java
        │                   ├── ApiResponse.java
        │                   ├── Configuration.java
        │                   ├── GzipRequestInterceptor.java
        │                   ├── JSON.java
        │                   ├── Pair.java
        │                   ├── ProgressRequestBody.java
        │                   ├── ProgressResponseBody.java
        │                   ├── StringUtil.java
        │                   ├── api
        │                   │   ├── PetApi.java
        │                   │   ├── StoreApi.java
        │                   │   └── UserApi.java
        │                   ├── auth
        │                   │   ├── ApiKeyAuth.java
        │                   │   ├── Authentication.java
        │                   │   ├── HttpBasicAuth.java
        │                   │   ├── OAuth.java
        │                   │   └── OAuthFlow.java
        │                   └── model
        │                       ├── Category.java
        │                       ├── ModelApiResponse.java
        │                       ├── Order.java
        │                       ├── Pet.java
        │                       ├── Tag.java
        │                       └── User.java
        └── test
            └── java
                └── io
                    └── swagger
                        └── client
                            └── api
                                ├── PetApiTest.java
                                ├── StoreApiTest.java
                                └── UserApiTest.java
    
    18 directories, 49 files
    

Fazit

Schnittstellen-Dokumentation ist nicht mehr so langweilig und sperrig wie früher. Mit den entsprechenden Swagger-Werkzeugen macht das Erstellen, Ausprobieren und Dokumentieren einer Schnittstelle sogar Spaß.

Kommentare sind geschlossen.