Scribd
Upload
383 views

Use Swagger To Create Your API Documentation

This document discusses how to document an API using Swagger. Swagger allows defining a standard, language-agnostic interface for a REST API that both humans and computers can use to discover and understand the API's capabilities. It introduces Swagger Core, Editor, and UI, which are used to define an API specification in JSON or YAML format and generate API documentation. The specification can then be used by code generation tools to create server stubs and client libraries.

Uploaded by

renekuiper83
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
383 views

Use Swagger To Create Your API Documentation

This document discusses how to document an API using Swagger. Swagger allows defining a standard, language-agnostic interface for a REST API that both humans and computers can use to discover and understand the API's capabilities. It introduces Swagger Core, Editor, and UI, which are used to define an API specification in JSON or YAML format and generate API documentation. The specification can then be used by code generation tools to create server stubs and client libraries.

Uploaded by

renekuiper83
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 15

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

You might also like