Skip to content

Latest commit

 

History

History
231 lines (190 loc) · 6.11 KB

基本结构.md

File metadata and controls

231 lines (190 loc) · 6.11 KB
Raw

基本结构

Swagger定义可以用JSON或YAML编写。在本指南中，我们只使用了YAML示例，但是JSON也一样。用YAML编写的Swagger规范示例如下:

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

元数据

每个 Swagger 规范都以 Swagger 版本开始，2.0是最新版本(3.0才是最新的)。Swagger 版本定义了 API 规范的总体结构—您可以记录什么以及如何记录它。

swagger: "2.0"

然后，您需要指定APIinfo-title、description(可选)、version(API版本，而不是文件修订或Swagger版本)。

info:
  title: Sample API
  description: API description in Markdown.
  version: 1.0.0

version可以是一个随机的字符串.你可以用major.minor.patch(如语义版本控制)，或任意格式，如1.0-beta或2016.11.15。
description可以是多行的，并且支持 GitHub Flavored Markdown，用于丰富的文本表示。
info 还支持用于联系信息、许可证和其他详细信息的其他字段。参考: info对象。

Base URL

所有 API 调用的基本 URL 都是使用scheme、host和basePath定义的:

host: api.example.com
basePath: /v1
schemes:
  - https

所有 API 路径都相对于基本 URL。例如 /users 实际上意味着 https://api.example.com/v1/users 。 更多信息参考:API Host and Base URL。

Consumes, Produces

consumption和produces部分定义 API 支持的 MIME 类型。根级定义可以在单个操作中重写。

consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml

更过信息参考:MIME Types

Paths

Path 部分定义了 API 中的各个端点(路径)，以及这些端点支持的HTTP方法(操作)。例如，GET /users可以描述为:

paths:
  /users:
    get:
      summary: Returns a list of users.
      description: Optional extended description in Markdown.
      produces:
        - application/json
      responses:
        200:
          description: OK

更多信息参考: Paths and Operations

Parameters

操作可以有可以通过URL路径(/users/{userId})、查询字符串(/users?role=admin)、头(X-CustomHeader: Value)和请求体传递的参数。您可以定义参数类型、格式、它们是必需的还是可选的，以及其他细节:

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

更多信息参考: Describing Parameters

Responses

对于每个操作，您可以定义可能的状态代码，例如200 OK或404 Not Found，以及响应主体的schema。模式可以内联定义，也可以通过$ref从外部定义引用。您还可以为不同的内容类型提供示例响应。

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

更多信息参考: Describing Responses

Input and Output Models

全局definitions部分允许您定义API中使用的公共数据结构。无论何时需要schema(请求体和响应体)，都可以通过$ref引用它们。例如，这个JSON对象:

{
  "id": 4,
  "name": "Arthur Dent"
}

可以表示为：

definitions:
  User:
    properties:
      id:
        type: integer
      name:
        type: string
    # Both properties are required
    required:  
      - id
      - name

然后在请求体模式和响应体模式中引用如下:

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

securityDefinition和security关键字用于描述API中使用的身份验证方法。

securityDefinitions:
  BasicAuth:
    type: basic
security:
  - BasicAuth: []

受支持的身份验证方法包括:

更多信息参考: Authentication