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": "support@swagger.io"
  },
  "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: support@swagger.io
license:
  name: Apache 2.0
  url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1