[原创]使用 swagger 定义 API

使用 Swagger 定义API

1. Start Swagger Editor

   docker run -d -p 8080:8080 swaggerapi/swagger-editor
   

2. Open Swagger Editor in browser http://localhost:8080/

   https://swagger.io/tools/swagger-editor/download/
   https://github.com/swagger-api/swagger-editor

3. Example

   # Example
   swagger: '2.0'
   info:
     description: Test Server API
     version: 3.2.0
     title: Swagger For Test Server
     termsOfService: 'https://www.zhipeng.dev'
     contact:
       email: [email protected]
   externalDocs:
     description: Find out more about test server
     url: 'https://zhipeng.dev'
   host: '127.0.0.1:1029'
   basePath: /
   tags:
     - name: user
       description: User manager
   schemes:
     - http
   paths:
     /admin/user/add:
       get:
         tags:
           - user
         summary: create new user into the proxy server
         description: ''
         operationId: addUser
         produces:
           - application/json
         parameters:
           - name: name
             type: string
             required: true
             in: query
           - name: passwd
             type: string
             required: true
             in: query
         responses:
           '200':
             description: successful
             schema:
               $ref: '#/definitions/ApiResponse'
           '403':
             description: Forbiddend
         security:
           - APIToken: []
     /admin/user/del:
       get:
         tags:
           - user
         summary: delete a user
         description: ''
         operationId: delUser
         produces:
           - application/json
         parameters:
           - name: name
             type: string
             required: true
             in: query
         responses:
           '200':
             description: successful
             schema:
               $ref: '#/definitions/ApiResponse'
           '403':
             description: Forbiddend
         security:
           - APIToken: []
   
   securityDefinitions:
     APIToken:
       type: apiKey
       name: custom-token
       in: header
   
   definitions:
     ApiResponse:
       type: object
       properties:
         code:
           type: integer
         msg:
           type: string
           example: OK
         data:
           type: object
           
   

   Swagger Definition Objects Generator

   https://roger13.github.io/SwagDefGen/
   https://github.com/Roger13/SwaggerGenerator