swagger例子

Data Types

Primitive data types in the Swagger Specification are based on the types supported by the JSON-Schema Draft 4. Models are described using the Schema Object which is a subset of JSON Schema Draft 4.

An additional primitive data type "file" is used by the Parameter Object and the Response Object to set the parameter type or the response as being a file.

Primitives have an optional modifier property format. Swagger uses several known formats to more finely define the data type being used. However, the format property is an open string-valued property, and can have any value to support documentation needs. Formats such as "email", "uuid", etc., can be used even though they are not defined by this specification. Types that are not accompanied by a format property follow their definition from the JSON Schema (except for file type which is defined above). The formats defined by the Swagger Specification are:

Common Name	type	format	Comments
integer	integer	int32	signed 32 bits
long	integer	int64	signed 64 bits
float	number	float
double	number	double
string	string
byte	string	byte	base64 encoded characters
binary	string	binary	any sequence of octets
boolean	boolean
date	string	date	As defined by full-date - RFC3339
dateTime	string	date-time	As defined by date-time - RFC3339
password	string	password	Used to hint UIs the input needs to be obscured.

• 
  Describing Parameters

  /login:
    post:
      parameters:
        - in: formData
          name: account
          description: phone num
          type: string
          default: "13800138000"
        - in: formData
          name: password
          type: string
          format: password
          required: true
      responses:
        200:
          description: Echo test-path
          schema:
            $ref: "#/definitions/response"
          examples:
            application/json:
              {
                code: 404,
                message: 接口不存在,
                result:
                {
                  request: null,
                  code: 123456
                }
              }
definitions:
  response:
    type: object
    properties:
      code:
        type: integer
        description: 错误码
      message:
        type: string
        description: 错误信息
      result: 
        type: object
        properties:
          request:
            type: object

 

Parameter Types

Swagger distinguishes between the following parameter types based on the parameter location. The location is determined by the parameter’s in key, for example, in: query or in: path.

• query parameters, such as /users?role=admin            in: query
• path parameters, such as /users/{id}　　　　　　　　　　　 in: path
• header parameters, such as X-MyHeader: Value           in: header
• body parameters that describe the body of POST, PUT and PATCH requests (see Describing Request Body)      in: body
• form parameters – a variety of body parameters used to describe the payload of requests with Content-Type of application/x-www-form-urlencoded and multipart/form-data (the latter is typically used for file uploads)           in: formData
  
  

Required and Optional Parameters

Default Parameter Values

 

Enum Parameters

The enum keyword allows you to restrict a parameter value to a fixed set of values. The enum values must be of the same type as the parameter type.

        - in: query
          name: status
          type: string
          enum: [available, pending, sold]

More info: Defining an Enum.