REST  APIs  dokumentieren  mit  Swagger

Daniel  Pozzi,  FrOSCon 2015

Über  Swagger und  mich

2

https://github.com/bonndan https://swagger.io/Apache  2  license

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

Das  Herzstück:  die  JSON  Spezifikation

5

Aus  dem  Demo:https://goo.gl/If4I2t

SwaggerWorkflow

6

JSONSpezifikation

HTML  API  UI

SDK  Generierung

CodeAnnotation

Swagger Annotations

7

Swagger Annotationshttps://github.com/swagger-­‐api/swagger-­‐core/wiki/Annotations-­‐1.5.X

Für  PHP:  http://zircote.com/swagger-­‐php/annotations.html

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

Swagger nutzt  Mustache

9

Code:https://goo.gl/cdlXKl

Java  und  Swagger

Maven Swagger Plugin statt  Scala  Runtime!

10

https://github.com/leanix/swagger-­‐demo/blob/master/pom.xml#L77

Plugin:http://kongchen.github.io/swagger-­‐maven-­‐plugin

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 packenBespiel  mit  Dropwizard:  https://goo.gl/jSP0GN

• SwaggerUI kann  man  leicht  an  das  Unternehmens  – CI  anpassen,   im  demo-­‐Projekt  als  gitsubmodule

Referenzen und  mehr

12

Mehr:  http://swagger.io/open-­‐source-­‐integrations/

Code:https://github.com/leanix/swagger-­‐demo

Alternativen:https://raml.orghttps://github.com/mashery/iodocshttp://www.mashery.com/api/io-­‐docs