swagger-api-example
The render template this demo used is made by redoc.
You can alse upload the
swagger.jsonto swagger editor to see the official render template. (Please ignore the errors when uploading to swagger editor)For those who using vs code, you can easily preview the demo when editing
swagger.jsonby installing the Swagger Viewer plugin.
Installation
git clone https://github.com/HcwXd/swagger-api-example.git
cd ./swagger-api-example
Learn swagger through the example
- Open
index.htmlto see what's the finished document look like - Open
swagger.jsonwhich contains all the basics syntax needed for writing a simple swagger document
Learn swagger step by step
Swagger Structure Overview
A swagger document can be divided into three parts:
- Metadata
- Metadata of api document, including api version, test host, api category, etc.
- Api endpoints
- Define each api endpoints method, request, response.
- Reusable component
- Define component that can be reused for convenience when making document
Metadata
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Api Document Example",
"description": "這是一個學習如何使用 Swagger 產生 API Document 的範例。"
},
"schemes": ["http"],
"host": "myTestServer",
"basePath": "'v1",
"tags": [
{
"name": "learnRequest",
"description": "在這個分類學習如何描述 Request"
},
{
"name": "learnResponse",
"description": "在這個分類學習如何描述 Response"
}
],swagger: The swagger versioninfoversion: The api versiontitle: The title of the documentdescription: Description of the document- It's noteworthy that you can actually place description everywhere in a swagger document
- Test url
schemes,host,basePath- The three above determine the url that get the testing request
- For example, the above config send testing request to
http://myTestServer/v1
tags: Define the catagory of different api
Api endpoints
Basic Example
"paths": {
"/haveSomeParams/{someQuery}": {
"get": {
"tags": ["learnRequest"],
"summary": "如何描述在 query 中的參數",
"description": "如何描述在 query 中的參數",
"produces": ["application/json"],
"parameters": [
{
"in": "query",
"name": "someQuery",
"description": "參數在 query 中的例子",
"required": true,
"type": "string",
"schema": {
"type": "string",
"example": "yolo!"
}
}
]
}
},paths- Each api endpoint is defined under this level
- The method is defined after the api endpoint
tags: The catagory this api endpoint belong toproduces: The format of the outputparameters- Each parameter have several properties
in: Can be header, body, query, etcname: Name of the parameterrequired: Whether the parameter is required or optionaltype: The type of the parameterschema: The schema of the parameter, you can put example request parameter here. Also, you can put description here for more clarity
Request with different types in parameter
"/haveSomeParams": {
"post": {
"tags": ["learnRequest"],
"summary": "如何描述在 body 或 header 的參數",
"description": "如何描述在 body 或 header 的參數",
"consumes": ["application/json"],
"produces": ["application/json"],
"parameters": [
{
"in": "body",
"name": "body",
"description": "參數在 body 中的例子",
"required": true,
"type": "object",
"schema": {
"properties": {
"propString": {
"type": "string",
"example": "abcd",
"description": "這是一個字串的參數"
},
"propInt": { "type": "int", "example": 123, "description": "這是一個整數的參數" },
"propBoolean": {
"type": "boolean",
"example": false,
"description": "這是一個布林值的參數"
}
}
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"description": "參數在 header 中的例子，此處以 authorization 為例",
"type": "string",
"schema": {
"type": "string",
"example": "acde1jflk34fd21ekfkf",
"description": "這是一串秘密的授權碼"
}
}
]
}
},- As you can see, you can define object type of parameter by declaring its properties in schema
- And also, you can define parameter in header.
Define response
"/haveSomeResponse": {
"get": {
"tags": ["learnResponse"],
"summary": "如何描述不同的 Response",
"description": "如何描述不同的 Response",
"consumes": ["application/json"],
"produces": ["application/json"],
"responses": {
"200": {
"description": "這是一個成功 Response 的例子",
"type": "object",
"schema": {
"properties": {
"msg": {
"type": "string",
"example": "success",
"description": "成功 Response 在這裡會回傳 success"
},
"logCode": {
"type": "int",
"example": 2357,
"description": "這是一個成功 Response 後的追蹤 log code"
}
}
}
},
"400": {
"description": "缺少參數或參數格式不正確",
"type": "object",
"schema": {
"properties": {
"error": {
"type": "string",
"example": "params are invalid",
"description": "失敗 Response 的 error message"
}
}
}
}
}
}
},responses- Define response here followed by the status code
Reusable component
You can define reusable component for convenience when making document
"definitions": {
"successResponseSchema": {
"properties": {
"msg": {
"type": "string",
"example": "success",
"description": "成功 Response 在這裡會回傳 success"
},
"logCode": {
"type": "int",
"example": 2357,
"description": "這是一個成功 Response 後的追蹤 log code"
}
}
},
"headerParamExample": {
"name": "authorization",
"in": "header",
"required": false,
"description": "Example params in header",
"type": "string",
"schema": {
"type": "string",
"example": "acde1jflk34fd21ekfkf"
}
}
}definitions- You define your component under this level
- As you can see, you can define any kind of component in every level
- While
successResponseSchemadefine component at schema level,headerParamExampledefine at parameter level
- You use definitions by
"$ref": "#/definitions/yourComponentName"in the document
- You define your component under this level
Before
"/haveSomeResponse": {
"get": {
"tags": ["learnResponse"],
"summary": "如何描述不同的 Response",
"description": "如何描述不同的 Response",
"consumes": ["application/json"],
"produces": ["application/json"],
"responses": {
"200": {
"description": "這是一個成功 Response 的例子",
"type": "object",
"schema": {
"properties": {
"msg": {
"type": "string",
"example": "success",
"description": "成功 Response 在這裡會回傳 success"
},
"logCode": {
"type": "int",
"example": 2357,
"description": "這是一個成功 Response 後的追蹤 log code"
}
}
}
},
"400": {
"description": "缺少參數或參數格式不正確",
"type": "object",
"schema": {
"properties": {
"error": {
"type": "string",
"example": "params are invalid",
"description": "失敗 Response 的 error message"
}
}
}
}
}
}
},After
"/haveSomeParams/withDefinition": {
"post": {
"tags": ["learnDefinition"],
"summary": "如何使用 definition 在 Param 層級描述 Request",
"description": "definition 可以描述各種層級，也可以直接在參數層級定義 definition",
"consumes": ["application/json"],
"produces": ["application/json"],
"parameters": [
{
"$ref": "#/definitions/bodyParamExample"
},
{
"$ref": "#/definitions/headerParamExample"
}
]
}
}
}"definitions": {
"bodyParamExample": {
"in": "body",
"name": "body",
"description": "參數在 body 中的例子",
"required": true,
"type": "object",
"schema": {
"properties": {
"propString": {
"type": "string",
"example": "abcd",
"description": "這是一個字串的參數"
},
"propInt": { "type": "int", "example": 123, "description": "這是一個整數的參數" },
"propBoolean": {
"type": "boolean",
"example": false,
"description": "這是一個布林值的參數"
},
"propArray": {
"type": "array",
"example": [1, 2, 3],
"description": "這是一個陣列的參數"
},
"propObject": {
"type": "object",
"example": {
"prop1": 1234,
"prop2": "abcde",
"prop3": true
},
"description": "這是一個物件的參數"
}
}
}
},
"headerParamExample": {
"name": "authorization",
"in": "header",
"required": false,
"description": "Example params in header",
"type": "string",
"schema": {
"type": "string",
"example": "acde1jflk34fd21ekfkf"
}
}
}
The whole document in the example
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Api Document Example",
"description": "這是一個學習如何使用 Swagger 產生 API Document 的範例。"
},
"schemes": ["http", "https"],
"host": "localhost",
"basePath": "",
"tags": [
{
"name": "learnRequest",
"description": "在這個分類學習如何描述 Request"
},
{
"name": "learnResponse",
"description": "在這個分類學習如何描述 Response"
}
],
"paths": {
"/haveSomeParams/{someQuery}": {
"get": {
"tags": ["learnRequest"],
"summary": "如何描述在 query 中的參數",
"description": "如何描述在 query 中的參數",
"produces": ["application/json"],
"parameters": [
{
"in": "query",
"name": "someQuery",
"description": "參數在 query 中的例子",
"required": true,
"type": "string",
"schema": {
"type": "string",
"example": "yolo!"
}
}
]
}
},
"/haveSomeParams": {
"post": {
"tags": ["learnRequest"],
"summary": "如何描述在 body 或 header 的參數",
"description": "如何描述在 body 或 header 的參數",
"consumes": ["application/json"],
"produces": ["application/json"],
"parameters": [
{
"in": "body",
"name": "body",
"description": "參數在 body 中的例子",
"required": true,
"type": "object",
"schema": {
"properties": {
"propString": {
"type": "string",
"example": "abcd",
"description": "這是一個字串的參數"
},
"propInt": { "type": "int", "example": 123, "description": "這是一個整數的參數" },
"propBoolean": {
"type": "boolean",
"example": false,
"description": "這是一個布林值的參數"
}
}
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"description": "參數在 header 中的例子，此處以 authorization 為例",
"type": "string",
"schema": {
"type": "string",
"example": "acde1jflk34fd21ekfkf",
"description": "這是一串秘密的授權碼"
}
}
]
}
},
"/haveSomeResponse": {
"get": {
"tags": ["learnResponse"],
"summary": "如何描述不同的 Response",
"description": "如何描述不同的 Response",
"consumes": ["application/json"],
"produces": ["application/json"],
"responses": {
"200": {
"description": "這是一個成功 Response 的例子",
"type": "object",
"schema": {
"properties": {
"msg": {
"type": "string",
"example": "success",
"description": "成功 Response 在這裡會回傳 success"
},
"logCode": {
"type": "int",
"example": 2357,
"description": "這是一個成功 Response 後的追蹤 log code"
}
}
}
},
"400": {
"description": "缺少參數或參數格式不正確",
"type": "object",
"schema": {
"properties": {
"error": {
"type": "string",
"example": "params are invalid",
"description": "失敗 Response 的 error message"
}
}
}
}
}
}
},
"/haveSomeResponse/withDefinition": {
"get": {
"tags": ["learnDefinition"],
"summary": "如何使用 definition 在 Schema 層級描述 Response",
"description": "definition 是可以重複使用的物件簡寫，可以用 `\"$ref\" : \"#/definitions/modelName\"` 存取\n",
"consumes": ["application/json"],
"produces": ["application/json"],
"responses": {
"200": {
"description": "這是一個成功 Response 的例子",
"schema": { "$ref": "#/definitions/successResponseSchema" }
},
"400": {
"description": "缺少參數或參數格式不正確",
"schema": { "$ref": "#/definitions/invalidRequestResponseSchema" }
},
"401": {
"description": "帳號或密碼錯誤",
"schema": {
"$ref": "#/definitions/loginFailResponseSchema"
}
}
}
}
},
"/haveSomeParams/withDefinition": {
"post": {
"tags": ["learnDefinition"],
"summary": "如何使用 definition 在 Param 層級描述 Request",
"description": "definition 可以描述各種層級，也可以直接在參數層級定義 definition",
"consumes": ["application/json"],
"produces": ["application/json"],
"parameters": [
{
"$ref": "#/definitions/bodyParamExample"
},
{
"$ref": "#/definitions/headerParamExample"
}
]
}
}
},
"definitions": {
"successResponseSchema": {
"properties": {
"msg": {
"type": "string",
"example": "success",
"description": "成功 Response 在這裡會回傳 success"
},
"logCode": {
"type": "int",
"example": 2357,
"description": "這是一個成功 Response 後的追蹤 log code"
}
}
},
"invalidRequestResponseSchema": {
"properties": {
"error": {
"type": "string",
"example": "params are invalid",
"description": "失敗 Response 的 error message"
}
}
},
"loginFailResponseSchema": {
"properties": {
"error": {
"type": "string",
"example": "Unauthorized",
"description": "失敗 Response 的 error message"
}
}
},
"bodyParamExample": {
"in": "body",
"name": "body",
"description": "參數在 body 中的例子",
"required": true,
"type": "object",
"schema": {
"properties": {
"propString": {
"type": "string",
"example": "abcd",
"description": "這是一個字串的參數"
},
"propInt": { "type": "int", "example": 123, "description": "這是一個整數的參數" },
"propBoolean": {
"type": "boolean",
"example": false,
"description": "這是一個布林值的參數"
},
"propArray": {
"type": "array",
"example": [1, 2, 3],
"description": "這是一個陣列的參數"
},
"propObject": {
"type": "object",
"example": {
"prop1": 1234,
"prop2": "abcde",
"prop3": true
},
"description": "這是一個物件的參數"
}
}
}
},
"headerParamExample": {
"name": "authorization",
"in": "header",
"required": false,
"description": "Example params in header",
"type": "string",
"schema": {
"type": "string",
"example": "acde1jflk34fd21ekfkf"
}
}
}
}
Advance Example
Docker API Documentation
Live Demo ( You can download yaml file on the website )