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
- Schnittstellen-Dokumentation erstellen und bearbeiten (nutzt Swagger UI)
- Online-Beispiel: https://editor.swagger.io/
- Lokal:
docker run -d -p 80:8080 swaggerapi/swagger-editor - Browser: http://localhost/
- File -> Import URL: https://petstore.swagger.io/v2/swagger.json
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ß.