Using-Swagger-for-your-API-documentation

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
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
API declaration
Specification
Demo
Specification
Frontend
Backend
api-docs
{specification}
Interpretation
Validation
webservices
API
CRUD
Database
Specification webservices
api_doc
No webservice
Resource listing
Webservice
Webservice doc
{specification}
/servoy-service/rest_ws/<module name>/api_doc/<apiKey>/<webservice>
Document generation
onSolutionOpen
api_webservice
(base form)
ws_create
ws_read
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

Download Report