Documenting your API with

Swagger
• 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
Swagger Core
Editor

{specification
}
json, yaml

Swagger
Swagger UI
Codegen

Introducing Swagger
 Swagger UI Webserver

HTML
{specification CSS
}
JS
json, yaml

/api-docs

Swagger UI
 {specification 1.2} {specification 2.0}
json json, yaml

Resource
swagger.json
listing

API
declaration
API
declaration

Specification
Demo

Specification
 Backend Frontend

{specification api-docs
}

Interpretation
Validation

webservices
API
CRUD

Database

Specification webservices
 api_doc

No webservice Webservice

Resource Webservice
listing {specification
doc
}

servoy-service/rest_ws/<module name>/api_doc/<apiKey>/<webservice>

Document generation
 onSolutionOpe For each
defined
n webserv
ice
api_webservi ws_create
ce ws_read
(base form) ws_update
ws_delete
{specification
} “contact” webservice
contact
(cloned
form)
“country” webservice country
(cloned
form)

/servoy-service/rest_ws/<module name>/<form name>/<apiKey>

Webservice generation
API docs
/servoy-service/rest_ws/<module name>/api_doc/<apiKey>/<webservice>

 /api-doc/<apiKey>/<webservice>

API
/servoy-service/rest_ws/<module name>/<form name>/apiKey

 /api/<apiKey>/<webservice>

URL Rewrite
• Tuckey’s UrlRewriteFilter

• Add urlrewritefilter-4.0.3.jar to \server\webapps\ROOT\WEB-INF

• Add snippet to \server\webapps\ROOT\WEB-INF\web.xml:

<filter>
<filter-name>UrlRewriteFilter</filter-name>
<filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>

</filter>
<filter-mapping>
<filter-name>UrlRewriteFilter</filter-name>
<url-pattern>/*</url-pattern>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
</filter-mapping>

URL Rewrite
• Add rules to \server\webapps\ROOT\WEB-INF\rewrite.xml
<rule match-type="wildcard">
<from>/api/**</from>
<to>/servoy-service/rest_ws/mSTB_api/$1</to>
</rule>
<rule match-type="wildcard">
<from>/api-doc/**</from>
<to>/servoy-service/rest_ws/mSTB_api/api_doc/$1</to>
</rule>

• Velocity:
<rule match-type="wildcard">
<from>/api-doc/**</from>
<to>/servoy-service/velocity/mSTB_api/api_doc/$1</to>
</rule>
<rule match-type="wildcard">
<from>/api/**</from>
<to>/servoy-service/velocity/mSTB_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 UrlRewriteFilter
http://tuckey.org/urlrewrite/

Resources