RESTful service documentation - TeamLeap/leapapp GitHub Wiki

What is Swagger?

The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.

Pre-requisites

To help you understand what the definition looks like, take a look at the following sample: { "swagger": "2.0", "info": { "title": "EMM Water Location Details", "description": "A service to retrieve EMM water location", "version": "1.0.0" }, "host": "wmdev.ekurhuleni.gov.za:5555", "schemes": [ "http" ], "basePath": "/rest/EMMWater", "produces": [ "application/json" ], "paths": { "/waterLongLati": { "get": { "summary": "Water Meters", "description": "The Water Meter endpoint returns information about the *meters* within EMM\noffered at a given location. The response includes the address\nand other details about each water meter, and water meters in the\nproper display order.\n", "tags": [ "Water" ], "responses": { "200": { "description": "An array of water cordinates", "schema": { "type": "array", "items": { "$ref": "#/definitions/Water" } } }, "default": { "description": "Unexpected error", "schema": { "$ref": "#/definitions/Error" } } } } } }, "definitions": { "Water": { "type": "object", "properties": { "address": { "type": "string", "description": "The address of the water meter location. For example, BENONI HOUSE TAP - ALPHEN PARK." }, "lattitude": { "type": "string", "description": "The lattitude of the water meter." }, "longitude": { "type": "string", "description": "The lattitude of the water meter." }, "code": { "type": "string", "description": "code." }, "image": { "type": "string", "description": "Unique identifier representing a specific water meter." } } }, "Error": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "fields": { "type": "string" } } } } }

In the sample above we describe a simple “EMM Water Location Details API”. It has a single URL exposed – “/waterLongLati”. We also describe the successful response, and mention it’s a string as well. A generic 400 error can be received if the “ waterLongLati” contained invalid characters. You can also see that throughout the operation itself we provide additional documentation.

ESB

Within ESB, A developer will create a pub folder under your package and copy your json or yaml file (create above) into this folder.

Using Swagger UI (hosted locally within EMM infrastructure)

All resources for the API are now viewable through the Swagger UI tool. They are grouped together based on the tags that they have been configured with. If no tags have been included in the configuration of a resource, then the Swagger UI tool automatically groups these under a ‘default’ tag. Swagger UI allows anyone — be it your development team or your end consumers — to visualize and interact with the API’s resources without having any of the implementation logic in place. It’s automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.

DEMO

Go to http://petstore.swagger.io/ and paste the URI from the ESB where the yaml or json file is located. e.g. http://esbservername:port:/rest/yourpackagename/pub/swagger.json

Click on any resource, e.g. /waterLongLati, to show all details about the resource and its parameters. There is also an option to try out the resource.