Swagger 规范

简介

Swagger Specification（Swagger 规范），现在称作 OpenAPI Specification （OpenAPI 规范）。

OpenAPI 规范定义了如何去描述你的 API 信息。

OpenAPI 规范允许你以 json 或 yaml 的语法格式，来编写 Swagger 文件。

基本结构

在 Swagger 文件中，你可以使用 json 或 yaml 的语法，来描述你的 API 。

这里，我们以 yaml 为例，来介绍 Swagger 文档（文件）的基本结构。

下面是一个例子 demo.yaml。

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in CommonMark or HTML.
      responses:
        '200':    # status code
          description: A JSON array of user names
          content:
            application/json:
              schema: 
                type: array
                items: 
                  type: string

注：所有的关键字都区分大小写。

Metadata（元数据）

openapi

定义本文档使用的 Swagger 规范的版本。

info

info 代码块，用于定义 API 整体的信息，如标题、描述、版本等。

servers

servers 代码块，用于定义你的 API 服务器的地址。

你也可以定义多个地址（一个沙箱环境，一个正式环境）。

在 swagger 2.0 规范中，用的是 host 代码块。

tags

用于定义你的 API 的类别。

tags:
- name: "article"
  description: "Access to Petstore orders"
- name: "user"
  description: "Operations about user"

paths

paths 代码块，用于定义具体的 API 接口的信息。

• /user 具体的 API 名称
• post 请求类型
• tags 对应上面的 tags 中的 name 的值
• summary 摘要
• description 描述信息
• parameters 请求参数
• responses 响应结果