Swagger Introduction & Examples
- Quick Start
- OpenAPI & Swagger
- Introduction to OpenAPI Specification
- Introduction to Swagger Open Source Tools
- asciidoctor
Quick Start
- install: after git clone, execute commands below in root directory:
swagger-server/bin/install.sh
doing that will produce some client SDKs, server code, asciidoc and html documents, look like this:
+---asciidoc //asciidoc document
+---client //auto Generated client SDKs
| +---go //-- client SDK in go programming language
| +---html2 //-- html document
| \---java //-- client SDK in java programming language
+---docs //html document
| swagger-example.html
+---server //auto generated server code
| +---jaxrs-resteasy //-- jaxrs server code that uses resteasy
| \---spring //-- server code that uses spring mvc
\---swagger-server // example
- run swagger-server:
java -jar swagger-server/target/swagger-server-${version}.jar
- explore:
swagger.json: http://127.0.0.1:8080/v2/api-docs
swagger-ui: http://127.0.0.1:8080/swagger-ui.html
Introduction to OpenAPI & Swagger Open Source Tools
OpenAPI & Swagger
OpenAPI
OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:
- Available endpoints (
/users
) and operations on each endpoint (GET /users
,POST /users
) - Operation parameters Input and output for each operation
- Authentication methods
- Contact information, license, terms of use and other information.
API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines. The complete OpenAPI Specification can be found on GitHub: OpenAPI 2.0 Specification, OpenAPI 3.0 Specification
Swagger
Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs. The major Swagger tools include:
- Swagger Editor – browser-based editor where you can write OpenAPI specs.
- Swagger Codegen – generates server stubs and client libraries from an OpenAPI spec.
- Swagger UI – renders OpenAPI specs as interactive API documentation.
Why Use OpenAPI?
The ability of APIs to describe their own structure is the root of all awesomeness in OpenAPI. Once written, an OpenAPI specification and Swagger tools can drive your API development further in various ways:
- Design-first users: use Swagger Codegen to generate a server stub for your API. The only thing left is to implement the server logic – and your API is ready to go live!
- Use Swagger Codegen to generate client libraries for your API in over 40 languages.
- Use Swagger UI to generate interactive API documentation that lets your users try out the API calls directly in the browser.
- Use the spec to connect API-related tools to your API. For example, import the spec to SoapUI to create automated tests for your API.
- And more! Check out the open-source tools that integrate with Swagger.
Introduction to OpenAPI Specification
Basic Structure
Swagger can be written in JSON or YAML. In this guide, we only use YAML examples, but JSON works equally well. A sample Swagger specification written in YAML looks like:
swagger: "2.0"
info:
title: Sample API
description: API description in Markdown.
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
Metadata
Every Swagger specification starts with the Swagger version, 3.0 being the latest version. A Swagger version defines the overall structure of an API specification -- what you can document and how you document it.
swagger: "2.0"
Then, you need to specify the API info
-- title
, description
(optional), version
(API version, not file revision or Swagger version).
info:
title: Sample API
description: API description in Markdown.
version: 1.0.0
version
can be a random string. You can use major.minor.patch (as in semantic versioning), or an arbitrary format like 1.0-beta or 2016.11.15.
description
can be multiline and supports GitHub Flavored Markdown for rich text representation.
info
also supports other fields for contact information, license and other details. Reference: Info Object.
Base URL
The base URL for all API calls is defined using schemes
, host
and basePath
:
host: api.example.com
basePath: /v1
schemes:
- https
All API paths are relative to the base URL. For example, /users actually means *https://api.example.com/v1/users.
More info*: API Host and Base URL.
Consumes, Produces
The consumes
and produces
sections define the MIME types supported by the API. The root-level definition can be overridden in individual operations.
consumes:
- application/json
- application/xml
produces:
- application/json
- application/xml
More info: MIME Types.
Paths
The paths
section defines individual endpoints (paths) in your API, and the HTTP methods (operations) supported by these endpoints. For example, GET /users
can be described as:
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in Markdown.
produces:
- application/json
responses:
200:
description: OK
More info: Paths and Operations.
Parameters
Operations can have parameters that can be passed via URL path (/users/{userId}
), query string (/users?role=admin
), headers (X-CustomHeader: Value
) and request body.
You can define the parameter types, format, whether they are required or optional, and other details:
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: Parameter description in Markdown.
responses:
200:
description: OK
More info: Describing Parameters.
Responses
For each operation, you can define possible status codes, such as 200 OK or 404 Not Found, and schema
of the response body.
Schemas can be defined inline or referenced from an external definition via $ref
. You can also provide example responses for different content types.
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: The ID of the user to return.
responses:
200:
description: A User object.
schema:
type: object
properties:
id:
type: integer
example: 4
name:
type: string
example: Arthur Dent
400:
description: The specified user ID is invalid (e.g. not a number).
404:
description: A user with the specified ID was not found.
default:
description: Unexpected error
More info: Describing Responses.
Input and Output Models
The global definitions
section lets you define common data structures used in your API. They can be referenced via $ref
whenever a schema
is required -- both for request body and response body. For example, this JSON object:
{
"id": 4,
"name": "Arthur Dent"
}
can be represented as:
definitions:
User:
properties:
id:
type: integer
name:
type: string
# Both properties are required
required:
- id
- name
and then referenced in the request body schema and response body schema as follows:
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
responses:
200:
description: OK
schema:
$ref: '#/definitions/User'
/users:
post:
summary: Creates a new user.
parameters:
- in: body
name: user
schema:
$ref: '#/definitions/User'
responses:
200:
description: OK
Authentication
The securityDefinitions
and security
keywords are used to describe the authentication methods used in your API.
securityDefinitions:
BasicAuth:
type: basic
security:
- BasicAuth: []
Supported authentication methods are:
- Basic authentication
- API key (as a header or query parameter)
- OAuth 2 common flows (implicit, password, application and access code)
More info: Authentication.
Introduction to Swagger Open Source Tools
Swagger Editor
Design, describe, and document your API on the first open source editor fully dedicated to OpenAPI-based APIs. The Swagger Editor is great for quickly getting started with the OpenAPI (formerly known as the Swagger Specification) specification, with support for Swagger 2.0 and OpenAPI 3.0.
- Runs Anywhere: The Editor works in any development environment, be it locally or in the web
- Smart Feedback: Validate your syntax for OAS-compliance as you write it with concise feedback and error handling
- Instant Visualization: Render your API specification visually and interact with your API while still defining it
- Intelligent Auto-completion: Write syntax faster with a smart and intelligent auto-completion
- Fully Customizable: Easy to configure and customize anything, from line-spacing to themes
- All About Your Build: Generate server stubs and client libraries for your API in every popular language
Swagger Codegen
Swagger Codegen can simplify your build process by generating server stubs and client SDKs for any API, defined with the OpenAPI (formerly known as Swagger) specification, so your team can focus better on your API’s implementation and adoption.
- Generate Servers: Remove tedious plumbing and configuration by generating boilerplate server code in over 20 different languages
- Improve API Consumption: Generate client SDKs in over 40 different languages for end developers to easily integrate with your API
- Continuously Improved: Swagger Codegen is always updated with the latest and greatest changes in the programming world
Swagger UI
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 OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back end implementation and client side consumption.
- Dependency Free: The UI works in any development environment, be it locally or in the web
- Human Friendly: Allow end developers to effortlessly interact and try out every single operation your API exposes for easy consumption
- Easy to Navigate: Quickly find and work with resources and endpoints with neatly categorized documentation
- All Browser Support: Cater to every possible scenario with Swagger UI working in all major browsers
- Fully Customizable: Style and tweak your Swagger UI the way you want with full source code access
- Complete OAS Support: Visualize APIs defined in Swagger 2.0 or OAS 3.0
asciidoctor
- asciidoc
- asciidoctor
Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby, packaged and distributed as a gem to RubyGems.org, and packaged for popular Linux distributions, including Fedora, Debian, Ubuntu, and Alpine. Asciidoctor can be run on the JVM using AsciidoctorJ and in all JavaScript environments using Asciidoctor.js. Asciidoctor is open source software and hosted on GitHub.