3.5.4.Swagger/OAI Specifications, Part 2 of 3

• 以下範例參考自https://github.com/acloudfan/REST-API-course-swagger (branch: definitions)

  • Swagger 2.0 Part 2包含:

    • 1.defining schema for request/response

      • JSON schema

      • examples

        definitions:
        # A general message schema in case of an error
        GeneralError:
          required:
            - message
          properties:
            message:
              type: string
        # A Not found error that is sent back in case no results are found for the 
        # requested resource
        NotFoundError:
          required:
            - message
            - hint
          properties:
            message:
              type: string
            hint:
              type: string
        
        Vacation:
          required:
            - name
            - description
            - type
            - numOfNights
          properties:
            # Name of the package
            name:
              type: string
            # Description of the package
            description:
              type: string
        
            # Type of the vacation package - shows how to use enumerations 
              type:
                type: string
                enum:
                  - resort
                  - cruise
            # All the destinations included in the vacation package  
            # Shows how to use array of complex objects
              destinations:
                type: array
                # There should be at least 1 destination in the package
                minItems: 1
                maxItems: 6
                items:
                  $ref: "#/definitions/Location"
        
            # Number of nights
              numOfNights:
                type: number
                minimum: 1
                maximum: 31
        
        # Definition for the location schema    
        # Refered from the destinations in Vacation schema
        Location:
          required:
            - city
            - country
          properties:
            city:
              type: string
            country:
              type: string

    • 2.parameters

      • request: head, body, query string

        # Parameter Definitions
        # Common parameters used in the operations
        parameters:
        IdInPath:
          name: id
          in: path
          type: string
          required: true

    • 3.security schema

    # Security Definitions
    securityDefinitions:
      KeySecurity:
        type: apiKey
          in: query
          name: api_key