Documenting your API with Swagger Ruben de Jong

• Free and open source framework • Define a standard, language-agnostic interface to a REST API • Allow both humans and computers to discover and understand the capabilities of the service Introducing Swagger

• Specification donated to Open API Initiative (OAI) per 1 -1 -2016 • Linux Foundation Collaboration Project Introducing Swagger

Swagger Core Swagger Editor {specification} json, yaml Swagger Codegen Introducing Swagger UI

Swagger UI Webserver HTML {specification} json, yaml CSS JS /api-docs Swagger UI

{specification 1. 2} json {specification 2. 0} json, yaml Resource listing swagger. json API declaration Specification

Demo Specification

Frontend Backend api-docs {specification} Interpretation Validation API webservices CRUD Database Specification webservices

$api_doc No webservice Resource listing Webservice doc {specification} /servoy-service/rest_ws/<module name>/api_doc/<api. Key>/<webservice> Document generation$

api_doc No webservice Resource listing Webservice doc {specification} /servoy-service/rest_ws/<module name>/api_doc/<api. Key>/<webservice> Document generation

$on. Solution. Open For each d efined we bservice api_webservice (base form) {specification} ws_create$

on. Solution. Open For each d efined we bservice api_webservice (base form) {specification} ws_create ws_read ws_update ws_delete “contact” webservice contact (cloned form) “country” webservice country (cloned form) /servoy-service/rest_ws/<module name>/<form name>/<api. Key> Webservice generation

API docs /servoy-service/rest_ws/<module name>/api_doc/<api. Key>/<webservice> /api-doc/<api. Key>/<webservice> API /servoy-service/rest_ws/<module name>/<form name>/api. Key /api/<api. Key>/<webservice> URL Rewrite

• Tuckey’s Url. Rewrite. Filter • Add urlrewritefilter-4. 0. 3. jar to serverwebappsROOTWEB-INF • Add snippet to serverwebappsROOTWEB-INFweb. xml: <filter> <filter-name>Url. Rewrite. Filter</filter-name> <filter-class>org. tuckey. web. filters. urlrewrite. Url. Rewrite. Filter</filter-class> </filter> <filter-mapping> <filter-name>Url. Rewrite. Filter</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> <dispatcher>FORWARD</dispatcher> </filter-mapping> URL Rewrite

• Add rules to serverwebappsROOTWEB-INFrewrite. xml <rule match-type="wildcard"> <from>/api/**</from> <to>/servoy-service/rest_ws/m. STB_api/$1</to> </rule> <rule match-type="wildcard"> <from>/api-doc/**</from> <to>/servoy-service/rest_ws/m. STB_api/api_doc/$1</to> </rule> • Velocity: <rule match-type="wildcard"> <from>/api-doc/**</from> <to>/servoy-service/velocity/m. STB_api/api_doc/$1</to> </rule> <rule match-type="wildcard"> <from>/api/**</from> <to>/servoy-service/velocity/m. STB_api/api_webservice/$1</to> </rule> URL Rewrite

Questions

• Swagger http: //swagger. io/ • Eclipse JSON Tools https: //bitbucket. org/denmiroch/jsontools/wiki/Home • Tuckey’s Url. Rewrite. Filter http: //tuckey. org/urlrewrite/ Resources