3.5.3.Swagger/OAI Specifications, Part 1 of 3

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

• Swagger 2.0 Part 1包含: 1.Metedata

  • info: Version, Title, description, contact, license

     # Swagger 2.0 always begin with the following
     swagger: "2.0"
    
     ########### Part 1 ###########
    
     info:
       version: "0.0.1"
       title: ACME Vacations API
       description: This specification is for the ACME Travel packages |
            These specifications were used to teach the students how
            to create the Swagger specifications for their REST API
       contact:
         name: A Cloud Fan
         url: http://www.acloudfan.com
         email: [e-mail]
    
       license:
         name: GNU
         url: http://acloudfan.com

  • 2.Root Document

    • The part of URL between the host:port and resource is referred to the specification as the basePath

    • host, basePath, schemes[string], consumes[string], produces[string]

      #during dev, should point to your local machine
      host: localhost:3000
      # basePath prefixes all resource paths- Version 1.0
      basePath: /v1/
      # 
      schemes:
      # tip: remove http to make production-grade
       - http
       - https
      # format of bodies a client can send (Content-Type)
      consumes:
       - application/json
      # format of the responses to the client (Accepts)
      produces:
       - application/json
      # Tags for ACME Travel API

  • 3.Tags

    • To make the specification searchable and filterable, it is suggested to use tags

    • name, description

      tags:
      - name: vacations
        description: Refer to vacation packages that are offered by ACME travel
      
      - name: hotels
        description: Refer to partner hotels through which ACME offers vacation |
                 deals.
      - name: package
        description: Same as vacations. It refers to the vacation package.

  • 4.External Documentation

    • The specification may linked with detailed document on a website by using the element externalDocs

    externalDocs:
        description: This is an external doc
        url: http://developer.acmetravel.com/docs

• Part 2

  • definitions

  • parameters

  • securityDefinition

• Part 3

  • Path