Mit Swagger gibt es seit einigen Jahren eine Möglichkeit REST-API sinnvoll zu dokumentieren und zu generieren. Aus einer YAML-Datei, welche die Beschreibung der API enthält kann mit dem Swagger Code Generator (kurz Swagger Codegen) eine entsprechende Client-Bibliothek oder ein Server-Stub erzeugt werden. Eine solche minimale YAML-Datei könnte wie folgt aussehen:
swagger: '2.0'
info:
description: "API"
version: "2018.04"
title: "API"
host: "api.example.com"
basePath: "/v1"
schemes:
- "https"
paths:
/tree:
get:
produces:
- "application/json"
summary: Returns the document tree
tags:
- "Document tree"
description: Lorem Ipsum dolor sit amet
responses:
200:
description: OK
In dieser Datei wird eine Ressource mit dem Namen tree und für diese eine Get-Methode definiert. Um daraus nun die Client-Bibliotheken bzw. Server-Stubs zu generieren muss der Swagger Codegen über Git bezogen, anschließend kompiliert und paketiert werden:
https://github.com/swagger-api/swagger-codegen.git cd swagger-codegen mvn clean package
Zur Erzeugung eines PHP-Server-Stubs mit dem Slim-Framework kann der Swagger Codegen anschließend wie folgt genutzt werden:
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i api.yaml -l slim -o folder/slim
Eine Client-Bibliothek wird auf dem gleichen Weg erzeugt:
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i api.yaml -l javascript -o folder/javascript
In diesem Fall wird eine JavaScript-Client-Bibliothek erzeugt. Die verfügbaren Sprachen bzw. Frameworks für die Clients und Server-Stubs erzeugt werden können, können mit dem Befehl:
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar langs
angezeigt werden. Die Ausgabe spezifiziert alle vorhandenen Generatoren:
Available languages: [ada, ada-server, akka-scala, android, apache2, apex, aspnetcore, bash, csharp, clojure, cwiki, cpprest, csharp-dotnet2, dart, elixir, elm, eiffel, erlang-client, erlang-server, finch, flash, python-flask, go, go-server, groovy, haskell-http-client, haskell, jmeter, jaxrs-cxf-client, jaxrs-cxf, java, inflector, jaxrs-cxf-cdi, jaxrs-spec, jaxrs, msf4j, java-pkmst, java-play-framework, jaxrs-resteasy-eap, jaxrs-resteasy, javascript, javascript-closure-angular, java-vertx, kotlin, lua, lumen, nancyfx, nodejs-server, objc, perl, php, powershell, pistache-server, python, qt5cpp, r, rails5, restbed, ruby, rust, rust-server, scala, scala-gatling, scala-lagom-server, scalatra, scalaz, php-silex, sinatra, slim, spring, dynamic-html, html2, html, swagger, swagger-yaml, swift4, swift3, swift, php-symfony, tizen, typescript-aurelia, typescript-angular, typescript-inversify, typescript-angularjs, typescript-fetch, typescript-jquery, typescript-node, undertow, ze-ph, kotlin-server]
Lizenziert ist der Swagger Codegen unter der Apache Licence in der Version 2 und somit freie Software.