{"id":244,"date":"2017-02-28T17:59:12","date_gmt":"2017-02-28T16:59:12","guid":{"rendered":"https:\/\/ulrich-schulte.net\/?p=244"},"modified":"2017-02-28T17:59:12","modified_gmt":"2017-02-28T16:59:12","slug":"swagger-2-0","status":"publish","type":"post","link":"https:\/\/ulrich-schulte.net\/?p=244","title":{"rendered":"Swagger 2.0"},"content":{"rendered":"<p><a href=\"http:\/\/swagger.io\">Swagger<\/a> ist ein Opensource-Framework zur Unterst\u00fctzung bei Design, Entwickelung, Test und Dokumentation von RESTful APIs.<\/p>\n<p>Mit der Version 2.0 werden dazu die Module<\/p>\n<ul>\n<li>Swagger Editor zum Design,<\/li>\n<li>Swagger Build zum Generieren von Clients und Servern,<\/li>\n<li>Swagger UI um Dokumentieren von Schnittstellen<\/li>\n<\/ul>\n<p>angeboten.<\/p>\n<h1>Entwicklung der Service-Dokumentation mit swagger-editor<\/h1>\n<p>In meinem Fall lag das RESTful API auf Serverseite schon vor. Ich wollte dieses API f\u00fcr Konsumenten der Schnittstelle dokumentieren. Dazu bietet sich das Javascript-basierte Module swagger-editor an. \u00a0Die Installation erfolgt einfach:<\/p>\n<p>Von github.io wird das Projekt<a href=\"https:\/\/github.com\/swagger-api\/swagger-editor\">\u00a0https:\/\/github.com\/swagger-api\/swagger-editor<\/a>\u00a0heruntergeladen, anschlie\u00dfend werden die notwendigen rpm-module mittels<\/p>\n<pre>$&gt; npm install<\/pre>\n<p>installiert. Durch Aufruf von<\/p>\n<pre>$&gt; npm start<\/pre>\n<p>wird dann der webbasierte Editor aufgerufen.<\/p>\n<p>Darin wird die Beschreibung des RESTful-API entweder in einer JSON-Struktur oder in der YAML-Schreibweise festgelegt. Die API-Definitionen k\u00f6nnen dort interaktiv getestet werden &#8211; einfach gro\u00dfartig, wie schnell man dort einen \u00dcberblick \u00fcber sein API bekommt.<\/p>\n<p>Ist die Definition der Schnittstelle &#8211; hier einen Clients &#8211; abgeschlossen, wird diese als JSON- oder als YAML-Datei auf einem Web-Server bereitgestellt.<\/p>\n<h1>Bereitstellen der Service-Dokumentation in Swagger-UI<\/h1>\n<p>swagger-editor ist ein Editor zum Entwickeln der Service-Beschreibung. Diese Modul ist nicht geeignet, um den eigenen Service f\u00fcr andere zu dokumentieren &#8211; in diesem Fall sollte die Service-Schnittstelle nicht mehr ver\u00e4nderbar sein.<\/p>\n<p>Genau diese Zweck erf\u00fcllt das Modul swagger-ui, welches man ebenfalls von <a href=\"https:\/\/github.com\/swagger-api\/swagger-ui\">github.io<\/a> herunterladen kann.<\/p>\n<p>Hat man dieses Modul heruntergeladen, so muss man noch den Verweis auf die zu testenden Schnittstelle eintragen.<\/p>\n<p>Dazu \u00e4ndert man in dist\/index.html den Verweis auf die weiter ob bereitgestellte eigene swagger.json -Datei.<\/p>\n<p>Anschliessend l\u00e4dt man den ganzen swagger-ui-Ordner auf den gew\u00fcnschten Web-Server.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Swagger ist ein Opensource-Framework zur Unterst\u00fctzung bei Design, Entwickelung, Test und Dokumentation von RESTful APIs. Mit der Version 2.0 werden dazu die Module Swagger Editor zum Design, Swagger Build zum Generieren von Clients und Servern, Swagger UI um Dokumentieren von Schnittstellen angeboten. Entwicklung der Service-Dokumentation mit swagger-editor In meinem Fall lag das RESTful API auf &hellip; <a href=\"https:\/\/ulrich-schulte.net\/?p=244\" class=\"more-link\"><span class=\"screen-reader-text\">Swagger 2.0<\/span> weiterlesen <span class=\"meta-nav\">&rarr;<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":false,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2},"jetpack_post_was_ever_published":false},"categories":[22],"tags":[24,25,23],"class_list":["post-244","post","type-post","status-publish","format-standard","hentry","category-swagger","tag-json","tag-restful","tag-swagger"],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p8NCNL-3W","jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=\/wp\/v2\/posts\/244","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=244"}],"version-history":[{"count":2,"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=\/wp\/v2\/posts\/244\/revisions"}],"predecessor-version":[{"id":246,"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=\/wp\/v2\/posts\/244\/revisions\/246"}],"wp:attachment":[{"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=244"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=244"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/ulrich-schulte.net\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=244"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}