An OpenAPI specification (OAS) is essentially a JSON file that contains information about your RESTful API. This can be incredibly useful for documenting and testing your APIs. Once you create your OAS, you can use Swagger UI to turn your OAS into a living and interactive piece of documentation that other programmers can use.
Typically, there are libraries that can analyze all of your routes and automtaically generate an OAS for you, or at least a majority of it for you. Sometimes, it’s not feasible to generate it automatically, or you might want to understand why your OAS is not generating the correct interface.
So in this tutorial, we’ll learn OpenAPI in 15 minutes, starting right now.
First, here is the Swagger UI generated by the OAS we will be examining.
This is what an example “products” GET route with query parameters will look in Swagger UI when expanded:
And lastly, here is what a parameterized route will look like:
The routes can be tested inside of Swagger UI, and you can see that they are documented and simple to use. A Swagger UI page can easily be automatically generated if you have the OpenAPI spec (OAS) completed, so the OAS is really the most important part. Below are all of the major pieces of an OAS.
{
# Set your OpenAPI version, which has to be at least 3.0.0
"openapi": "3.0.0",
# Set meta-info for OAS
"info": {
"version": "1.0.0",
"title": "Henry's Product Store",
"license": {
"name": "MIT"
}
},
# Set the base URL for your API server
"servers": [
{
# Paths will be appended to this URL
"url": "http://henrysproductstore/v1"
}
],
# Add your API paths, which extend from your base path
"paths": {
# This path is http://henryproductstore/v1/products"
"/products": {
# Specify one of get, post, or put
"get": {
# Add summary for documentation of this path
"summary": "Get all products",
# operationId is used for code generators to attach a method name to a route
# So operation IDs are optional, and can be used to generate client code
"operationId": "listProducts",
# Tags are for categorizing routes together
"tags": [
"products"
],
# This is how you specify query parameters for your route
"parameters": [
{
"name": "count",
"in": "query",
"description": "Number of products you want to return",
"required": false,
# Schemas are like data types
# You can define custom schemas, which we will see later
"schema": {
"type": "integer",
"format": "int32"
}
}
],
# Document all possible responses to your routes
"responses": {
"200": {
"description": "An array of products",
"content": {
"application/json": {
"schema": {
# This "Products" schema is a custom type
# We will look at the schema definitions near the bottom
"$ref": "#/components/schemas/Products"
}
}
}
}
}
},
# This is a POST route on /products
# If a route has two or more of a POST/PUT/GET, specify it as one route
# with multiple HTTP methods, rather than as multiple discrete routes
"post": {
"summary": "Create a product",
"operationId": "createProduct",
"tags": [
"products"
],
"responses": {
"201": {
"description": "Product created successfully"
}
}
}
},
# This is how you create a parameterized route
"/products/{productId}": {
"get": {
"summary": "Info for a specific product",
"operationId": "getProductById",
"tags": [
"products"
],
# Parameterized route section is added here
"parameters": [
{
"name": "productId",
# For query parameters, this is set to "query"
# But for parameterized routes, this is set to "path"
"in": "path",
"required": true,
"description": "The id of the product to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully added product",
"content": {
"application/json": {
"schema": {
# Custom schema called "Product"
# We will next examine schema definitions
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
}
},
# Custom schema definitions are added here
# Note that ints, floats, strings, and booleans are built-in
# so you don't need to add custom schemas for those
"components": {
"schemas": {
# define your schema name
# custom schemas are referenced by "#/components/schemas/SCHEMA_NAME_HERE"
"Product": {
"type": "object",
# define which of the properties below are required
"required": [
"id",
"name"
],
# define all of your custom schema's properties
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
},
# Sometimes you will want to return an array of a custom schema
# In this case, this will return an array of Product items
"Products": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
If you want to try out the OAS above, here is a version of it with no comments that can be passed into Swagger UI or any Swagger editor, like https://editor.swagger.io/.
{
"openapi": "3.0.0",
"info": {
"version": "1.0.0",
"title": "Henry's Product Store",
"license": {
"name": "MIT"
}
},
"servers": [
{
"url": "http://henrysproductstore/v1"
}
],
"paths": {
"/products": {
"get": {
"summary": "Get all products",
"operationId": "listProducts",
"tags": [
"products"
],
"parameters": [
{
"name": "count",
"in": "query",
"description": "Number of products you want to return",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
}
],
"responses": {
"200": {
"description": "An array of products",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Products"
}
}
}
}
}
},
"post": {
"summary": "Create a product",
"operationId": "createProduct",
"tags": [
"products"
],
"responses": {
"201": {
"description": "Product created successfully"
}
}
}
},
"/products/{productId}": {
"get": {
"summary": "Info for a specific product",
"operationId": "getProductById",
"tags": [
"products"
],
"parameters": [
{
"name": "productId",
"in": "path",
"required": true,
"description": "The id of the product to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successfully added product",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Product": {
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
}
},
"Products": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Product"
}
}
}
}
}
henrydangprg 