3.5.5.Swagger/OAI Specifications, Part 3 of 3

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

  • Swagger 2.0 Part 3包含:

    • 1.Path

      # This is where the resource paths are defined
      paths:
      # Vacation API
      /vacations:
        get:
          description: Returns the collection of valid (i.e., last date >= today's date) vacation packages
          # Refer to the tags created earlier
          security:
          # Array elements needed only in case of OAuth otherwise MUST be empty. In case of OAuth array has the scopes
            - KeySecurity : []
      
          tags:
            - vacations
            - package
          # parameters: There are no parameters for this operation 
          responses:
            "200":
              description: Success
              schema:
                  # a pointer to a definition
                  $ref: "#/definitions/Vacations"
      
            "404":
              description: When a vacation package is NOT found
              schema:
                $ref: "#/definitions/NotFoundError"
      
          # responses may fall through to errors
          default:
            description: Error
            schema:
              $ref: "#/definitions/GeneralError"
      
      /vacations/{id}:
        get:
          summary: this is a get op
          description: Returns the vacation package identified by {id}
          tags:
            - vacations
            - packages
          externalDocs:
            description: Link to the /vacations ops details & flow
            url: http://www.acloudfan.com
      
          consumes: 
            - application/json
          produces: 
            - application/json
      
          parameters:
            - $ref : "#/parameters/IdInPath"
      
          responses:
            "200":
                description: Success
                schema:
                  $ref: "#/definitions/Vacation"
      
            "404":
                description: When a vacation package is NOT found
                schema:
                  $ref: "#/definitions/NotFoundError"
      
            # responses may fall through to errors
            default:
              description: Error
              schema:
                $ref: "#/definitions/GeneralError"
          security:
            # Array elements needed only in case of OAuth otherwise MUST be empty. In case of OAuth array has the scopes
            - KeySecurity : []

• 貼到Online editor上