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:

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