Als PDF, PPTX herunterladen
Hochgeladen vonLeanIX GmbH
LeanIX Swagger REST API @ Open Source Konferenz FrosCon, Sankt Augustin
Das Dokument behandelt die Dokumentation von REST-APIs mit Swagger, einschließlich der Verwendung von Swagger-UI-Demos und der JSON-Spezifikation. Es bietet Anleitungen zur Verwendung von Swagger-Annotations in verschiedenen Programmiersprachen und zeigt, wie man SDKs generiert und einige Tricks beim Umgang mit Swagger beachtet. Zudem werden Alternativen zu Swagger wie RAML und IODocs erwähnt.
LeanIX Swagger REST API @ Open Source Konferenz FrosCon, Sankt Augustin
- 1. REST APIs dokumentieren mit Swagger Daniel Pozzi, FrOSCon 2015
- 2. Über Swagger und mich 2 https://github.com/bonndan https://swagger.io/ Apache 2 license
- 3. APIs für Nicht-‐EntwicklerSwagger-‐UI 3 Demo (swagger-‐demo starten): http://localhost:8080/docs/index.html?url=http://localhost:8080 /api-‐docs/swagger.json Offizieller Swagger demo pet store: http://petstore.swagger.io/ In Produktion: https://app.leanix.net/demo/api/v1/
- 4.
- 5. Das Herzstück: die JSON Spezifikation 5 Aus dem Demo: https://goo.gl/If4I2t
- 6. Swagger Workflow 6 JSON Spezifikation HTML API UI SDK Generierung Code Annotation
- 7. Swagger Annotations 7 Swagger Annotations https://github.com/swagger-‐api/swagger-‐core/wiki/Annotations-‐1.5.X Für PHP: http://zircote.com/swagger-‐php/annotations.html
- 8. SDK Generierung 8 Beispiel für PHP und Java: https://github.com/leanix/swagger-‐demo-‐codegen Konfiguration: https://goo.gl/plH6pB Ausführung (leanix/swagger-‐demo erforderlich): $ ./generate-‐php.sh $ ./generate-‐php.sh
- 9.
- 10. Java und Swagger MavenSwagger Plugin statt Scala Runtime! 10 https://github.com/leanix/swagger-‐demo/blob/master/pom.xml#L77 Plugin: http://kongchen.github.io/swagger-‐maven-‐plugin
- 11. Tricks und Fallen 11 •Vorsicht mit Enums in Swagger V1 • Map-‐artige Typen erfordern Handarbeit • Wie man Parameter verbirgt (Spec Filter): https://goo.gl/21qtz9 • Java: Swagger-‐UI, swagger.json in Uberjar packen Bespiel mit Dropwizard: https://goo.gl/jSP0GN • SwaggerUI kann man leicht an das Unternehmens – CI anpassen, im demo-‐Projekt als git submodule
- 12. Referenzen und mehr 12 Mehr: http://swagger.io/open-‐source-‐integrations/ Code: https://github.com/leanix/swagger-‐demo Alternativen: https://raml.org https://github.com/mashery/iodocs http://www.mashery.com/api/io-‐docs