Swagger Schema

Schema

Swagger Object

This is the root document object for the API specification. It combines what previously was the Resource Listing and API Declaration (version 1.2 and earlier) together into one document.

这是API规范的根文档对象。它把此前的资源列表（Resource Listing）和API声明（Declaration）(1.2 及更早版本) 放到了一个文档里。

Fixed Fields

Field Name	Type	Description
swagger	string	Required. Specifies the Swagger Specification version being used. It can be used by the Swagger UI and other clients to interpret the API listing. The value MUST be "2.0". 必须 定义了所使用的Swagger定义的版本。可以被Swagger UI和其他客户端解释API列表。这个必须是"2.0"`.
info	Info Object	Required. Provides metadata about the API. The metadata can be used by the clients if needed.必须字段提供了API的元数据信息。元数据必要的时候可以被客户端所使用。
host	string	The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the host is not included, the host serving the documentation is to be used (including the port). The host does not support path templating. 提供API服务的主机名称或者IP。这个字段必须只能是主机名，而不是包好阔scheme和子路径。该字段可以包括一个端口号。如果未指定host字段，提供当前文档本身的host将会被使用（包括端口）。host 字段不支持path templating.
basePath	string	The base path on which the API is served, which is relative to the host. If it is not included, the API is served directly under the host. The value MUST start with a leading slash (/). The basePath does not support path templating. 定义了提供API服务端的基础路径，这个路径是相对于host的。该字段的值必须开始于(/)。basePath 不支持path templating。
schemes	[string]	The transfer protocol of the API. Values MUST be from the list: "http", "https", "ws", "wss". If the schemes is not included, the default scheme to be used is the one used to access the Swagger definition itself. 定义了API的传输协议。取值必须为以下值之一： "http", "https", "ws", "wss"。如果没有指定schemes 字段，访问当前Swagger定义文件的默认scheme将会被使用。
consumes	[string]	A list of MIME types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under Mime Types.一个API可接受的MIME类型列表。这是对所有API的全局设置，但是可以被特定的API调用设置覆盖。取值必须是下面Mime Types所描述的。
produces	[string]	A list of MIME types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under Mime Types.一个API可能会返回的MIME类型列表。这是对所有API的全局设置，但是可以被特定的API调用设置覆盖。取值必须是下面Mime Types所描述的。
paths	Paths Object	Required. The available paths and operations for the API. 必须字段 定义了API中可用的路径以及操作。
definitions	Definitions Object	An object to hold data types produced and consumed by operations. 操作可能会接收或者返回的保存各种类型数据的对象。
parameters	Parameters Definitions Object	An object to hold parameters that can be used across operations. This property does not define global parameters for all operations. 可以跨操作传递参数的一个对象。这个属性不会为所有的操作定义参数。
responses	Responses Definitions Object	An object to hold responses that can be used across operations. This property does not define global responses for all operations. 可以被各个操作使用的持有应答信息的对象。这个属性不会为所有的操作定义全局的应答。
securityDefinitions	Security Definitions Object	Security scheme definitions that can be used across the specification. 被整个规范所使用的安全scheme定义。
security	[Security Requirement Object]	A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. 一个定义了哪种安全sheme整体应用到API的声明。值中列出了备选的安全scheme（也就是说安全要求之间是个逻辑OR的关系）。单个操作可以覆盖这个定义。
tags	[Tag Object]	A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. 被规范所使用的一组tag列表，带有附加的元数据。标签的属性努可以用来被解析工具用来反射他们的顺序。不是所有被Operation Object 所使用的标签都一定要声明。未声明的标签可以被随机的组织，或者按照工具的逻辑组织。列表中的每个标签必须是唯一的。
externalDocs	External Documentation Object	Additional external documentation. 附加的外部文档。

Patterned Objects

Field Pattern	Type	Description
^x-	Any	Allows extensions to the Swagger Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details. 允许对Swagger Schema进行扩展。这种字段名必须以x-为前缀，例如，x-internal-id。这个值可以设为null，一个原生类型，一个数组或者一个对象。参阅Vendor Extensions以获得进一步的细节。

Info Object

The object provides metadata about the API. The metadata can be used by the clients if needed, and can be presented in the Swagger-UI for convenience.

Fixed Fields

Field Name	Type	Description
title	string	Required. The title of the application. 必须字段 定义了应用的标题。
description	string	A short description of the application. [GFM syntax] (https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation. 一个对应用的简短描述。[GFM 语法] (https://help.github.com/articles/github-flavored-markdown) ，可被用来表现为富文本。
termsOfService	string	The Terms of Service for the API. API的服务条款。
contact	Contact Object	The contact information for the exposed API. 所导出的API的联系人信息。
license	License Object	The license information for the exposed API. 暴露的API的授权信息。
version	string	Required Provides the version of the application API (not to be confused with the specification version). 必须字段 提供了应用API的版本号（不要与Swagger规范的版本号搞混了）

Patterned Objects

Field Pattern	Type	Description
^x-	Any	Allows extensions to the Swagger Schema. The field name MUST begin with x-, for example, x-internal-id. The value can be null, a primitive, an array or an object. See Vendor Extensions for further details.

Info Object Example:

{
  "title": "Swagger Sample App",
  "description": "This is a sample server Petstore server.",
  "termsOfService": "http://swagger.io/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.swagger.io/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: http://swagger.io/terms/
contact:
  name: API Support
  url: http://www.swagger.io/support
  email: [email protected]
license:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1