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:

• 
  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.

swagger例子