Swagger is a Rest API representation.
Sometimes also be used as an interactive Rest API documentation, describing the formal description of the interface, generate client and server code.
I. Description Language: Spec
Swagger Swagger API Spec is the language used to describe the Rest API.
API can use yaml or json to represent.
Swagger API Spec contains the following sections:
Swagger, swagger spec specified version
info, to provide the metadata API
Tags, supplementary metadata in swagger ui are used as the packet label api
host, the host, if not provided, the document host where
basePath, relative to the path host of
schemes, API transport protocol, HTTP, HTTPS, WS, wss
Consumes, API can be consumed MIME type list
produces, MIME type list API generated
paths, API path, and each the method of HTTP path, a path together constitute a method of an HTTP operation . : Each operation has the following
label tags, the operation
summary, short summary
description, describing
externalDocs, external documents
unique string operationId, identifies the operation
consumes, consumption MIME type list
produces, produced a list of MIME type
parameters, parameter list
responses, Schema response status codes and messages to the
schemes, transmission protocols
deprecated, not recommended
Security, Safety
Data Type Definitions, the definition of consumption or production of API, using json-schema description, parameter and response can be part of an operation using the schema definitions section defined by reference
Parameters, common to a plurality of operating parameters
responses, in response to a plurality of common operating
securityDefinitions, security scheme defined
security, security claim
externalDocs, additional external document
One example of the operations described:
/pets/findByTags:
get:
tags:
- pet
summary: Finds Pets by tags
description: Muliple tags can be provided with comma seperated strings. Use tag1, tag2, tag3 for testing.
operationId: findPetsByTags
produces:
- application/json
- application/xml
parameters:
- in: query
name: tags
description: Tags to filter by
required: false
type: array
items:
type: string
collectionFormat: multi
responses:
"200":
description: successful operation
schema:
type: array
items:
$ref: "#/definitions/Pet"
"400":
description: Invalid tag value
security:
- petstore_auth:
- write_pets
- read_pets
Two, Swagger UI
Swagger UI Rest interface documentation for display.
Online access to the UI Swagger: HTTP: // petstore.swagger.io/
how to use? As long as the github project ( HTTPS: // github.com/swagger-api/ Swagger-ui ) downloaded to the local: Then open the dist / index.html with a browser can.
git clone https://github.com/swagger-api/swagger-ui.git
ps: swagger ui support Chinese version. Index.html method is to modify, add the following code in the head tag, introduced /lang/zh-cn.js
<script src='lang/translator.js' type='text/javascript'></script> <script src='lang/zh-cn.js' type='text/javascript'></script>
Third, Editor
Swagger Editor is Swagger API Spec editor, using yaml Swagger Editor to edit, file import and downloads but allows json yaml and both formats.
Download release: HTTPS: // github.com/swagger-api/ Swagger-Editor / Releases / download / v2.10.1 / swagger-editor.zip
Decompression, and then use the HTTP Server to load up a static file, the following is a node.js installed and up and running http server command
npm install -g http-server wget https://github.com/swagger-api/swagger-editor/releases/download/v2.10.1/swagger-editor.zip unzip swagger-editor.zip http-server -p 8080 swagger-editor
Enter the address can be edited in the browser
https://zhuanlan.zhihu.com/p/21353795