In the past, I heard different people talking about using Swagger.io for vastly different purposes. I was confused. Some folks were annotating their source code and using Swagger to produce documentation for their REST services. Others were using Swagger docs to automatically generate server-side product code. Others said they were generating mobile client-side code from a Swagger doc. What was going on?
It turns out they were all right.
The basic concept of Swagger.io remains the same. It's a simple standardized way to represent a REST interface in a document. However, there are now a significant number of tools packages available to produce and consume Swagger.io docs for various purposes.
First, I found a few blog articles from PointSource which caught my interest. http://www.pointsource.com/blog/3-best-practices-for-api-development-with-swagger
I also read a good portion of the Swagger spec: https://github.com/OAI/OpenAPI-Specification
Swagger has been donated to the open source community and renamed to Open API Specification.
I decided my first goal was to use the online Swagger Editor to define a simple hello world API, and then auto-generate a server-side instance and test it...
Using Swagger Editor
The Swagger Editor is an online tool: http://editor.swagger.io/#/
I poked around with it a little while. It's pretty straightforward. The left panel is an editor where you enter the representation of the API. The right panel is a live rendering of the Swagger docs created from the left panel.
Create the simplest API you can in the left panel. Scroll the right panel up and down until you like everything.
Export your definition to a local file for safe-keeping by clicking the upper left tab: File-> Download YAML.
Here is my YAML file. You are welcome to use it.
# This is an example Swagger API spec in YAML swagger: '2.0' info: title: Hello World API description: This is the exciting Hello World API version: "1.2.3" host: helloworld.com schemes: - https basePath: /v001 produces: - application/json paths: /healthcheck: get: summary: Returns a known response to indicate service status. description: The healthcheck endpoint returns status of the running service. tags: - User responses: 200: description: General information about the running service. schema: type: object properties: cpu: type: integer format: int32 message: type: string default: description: Unexpected error schema: $ref: '#/definitions/Error' definitions: Error: type: object properties: code: type: integer format: int32 description: Error code. message: type: string description: Human-readable error message.
Auto-generating a server-side instance
My next step was to download a node.js server-side instance which implemented my API.
From the Swagger Editor, click Generate Server-> Node.js It produces a zip file. Download it to your machine.
Unzip the file. Download the dependencies with 'npm install'. Start the server with 'node index.js'. Note that the server starts on port 8080 by default.
Confirm it works
The easiest way to confirm the endpoint works is to issue a REST request to it with cURL. Notice it renders the variable names specified in the YAML, and adds dummy values to them.
This completes the easy part:
- Manually defining a REST API using Swagger Editor
- Auto-generating a server-side instance in Node.js
- Verifying the server-side instance delivers the endpoint