Question

有没有一种方法可以根据API定义生成swagger.yaml。 API定义包括端点，标头，方法类型和示例请求有效负载。有什么方法可以使用工具或其他工具在线完成？

Answer 1

使用Swagger Editor。将您的端点，参数，请求和响应模型等转换为yaml定义。这是一个以以下内容开头的示例：

swagger: "2.0"                                # swagger version 

info:                                         # metadata
  version: 1.0.0            
  title: Test REST API
  description: Test REST API

basePath: /api                                # API base path  

paths:
  /ping:                                      # simple ping API definition  
      post:
        description: Ping API
        operationId: ping
        parameters:                           # request parameters definition
        - in: body                            # request body
          name: body
          description: request body model
          required: true
          schema:
            $ref: "#/definitions/Ping"
        - name: "test_header"                 # header parameter
          in: "header"
          required: false
          type: "string"
        responses:                            # response definition
          '200':
            description: pong
            schema:
              type: object
              items:
                $ref: '#/definitions/Pong'

definitions:                                  # request / response model definitions
  Ping:
    type: object
    properties:
      ping_attribute:
        type: string
        description: test request model attribute
  Pong:
    type: object
    properties:
      pong_attribute:
        type: string
        description: test response model attribute

尝试一下。

响应有效负载数组示例：

  OuterArrayModel:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: '#/definitions/InnerArrayModel'

  InnerArrayModel:
    type: object
    properties:
      lId:
        type: string
        example: "p"
      dLst:
        type: array
        items:
          $ref: '#/definitions/dLst'

  dLst:
    type: object
    properties:
      dId: 
        type: string
        example: "BC"
      Add:
        $ref: '#/definitions/Add'
      iDet:
        $ref: '#/definitions/iDet'
      cDet:
        $ref: '#/definitions/cDet'
      pDetails:
        $ref: '#/definitions/pDetails'


  Add: 
    type: object
    properties:
      Strt:
        type: string
        example: "q"
      Zip: 
        type: string
        example: "w"
      Cty: 
        type: string
        example: "e"
      State:
        type: string
        example: "r"
      Cntry:
        type: string
        example: "t"

  iDet: 
    type: object
    properties:
      aNme:
        type: string
        example: "y"
      iNme: 
        type: string
        example: "u"
      Dt: 
        type: string
        example: "20-apr"

  cDet: 
    type: object
    properties:
      custNme:
        type: string
        example: "i"
      cNme: 
        type: string
        example: "o"
      custPhne: 
        type: string
        example: "p"
      custEmail:
        type: string
        example: "a@b.com"

  pDetails: 
    type: object
    properties:
      Type:
        type: string
        example: "s"
      Number: 
        type: string
        example: "d"
      serial: 
        type: string
        example: "f"

根据API规范创建详尽的文档

1 个答案: