标签: swagger-editor

我正在用yaml写出我的招摇定义.假设我的定义看起来像这样.

paths:
  /payloads:
    post:
      summary: create a payload
      ...
      parameters:
      - in: body
        name: payload
        description: New payload
        required: true
        schema:
          $ref: "#/definitions/payload"
    put:
      summary: update a payload
      ...
      parameters:
      - in: body
        name: payload
        description: Updated existing payload
        required: true
        schema:
          $ref: "#/definitions/payload"
...
definitions:
  payload:
    properties:
      id:
        type: string
      someProperty:
        type: string
      ...

有没有办法可以指示PUT操作需要有效负载的id属性,并且POST操作是可选的(或者根本不应该出现)？

我正在使用在线Swagger编辑器为我的API创建Swagger规范.

我的API有一个GET请求端点,我使用以下YAML代码来描述输入参数:

paths:
  /fooBar:
    get:
      tags:
        - foobar
      summary: ''
      description: ''
      operationId: foobar
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          type: string
          example: 123, FakeStreet
        - name: city
          in: query
          description: City of the Address
          required: true
          type: string
          example: New York

如果我放入example标签,我会收到错误消息:

不是<#/ definitions/parameter>,<#/ definitions/jsonReference>中的一个

如何在Swagger中编写GET参数时设置示例？

我花了很多时间试图找到在Node.JS中创建swagger文档的解决方案.主库是swagger-node,在其中创建一个swagger yaml文件,然后将控制器添加到它.它会自动在您的应用中提供swagger ui文档,并根据您在yaml中指定的模型对请求和响应进行验证.

这很整洁,但是我要求我希望明确能够返回或接受某些字段null作为值,例如:

{ 
  id: 123,
  description: "string",
  date_sent: null
}

我不想删除date_sent密钥,我想明确地将其声明为null.

swagger规范不支持anyOfJSON模式通常如何做到这一点我相信.

我想知道是否有解决方法？也许某些库可用于具有x-nullable可以添加的供应商特定标志的节点,或者某种方式指定我的非必需字段应该都可以为空.

我是否必须自己写一些带有我的swagger文件的东西,然后在验证器中间件运行之前修改它,或者是否有某些可以建议的解决方法？

我正在使用YAML在Swagger编辑器中进行API定义.我试图代表以下响应主体:

{
    success: true,
    ids: [123456, ...]
}

这就是我的YAML的样子:

definitions:
  SuccessfulResponse:
    type: object 
    properties:
      success:
        type: boolean
        description: True if the all operations were successful
      ids:
        type: array
        items: 
          id: 
          type: string 

香港专业教育学院尝试了几种不同的方式,但是这样看似无效

如何正确描述上面给出的返回对象？

我试图在Swagger编辑器中获得一个多行文字(顺便说一下,这是一个很棒的工具!).

  post:
    summary: Translate one or more identifiers
    description: |
Translate one or more identifiers for one entity into the
identifiers of another entity. Translate one or more
identifiers for one entity into the identifiers of another entity.

    consumes:
    - application/json

我试过了| 和>,具有不同的结尾(增加缩进与空行),以及我能想到的每一种方式,但它总是给出相同的错误:

YAML Syntax Error
Can not read a block mapping entry; a multiline key may not be an implicit  
key at line 24, column 15: consumes: ^

我看到JS-YAML的错误表明问题是最终的Windows风格的换行符,我知道HTML textareas可以创建.这是我第一次真正使用YAML,那么只是我做错了什么,或者是Swagger编辑器中的错误？

我正在Swagger编辑器中编写YAML文件.

我的一个类型定义包含一个包含与父类型相同类型的子元素的数组.就是这样的:

definitions:
  TreeNode:
    type: object
    properties:
      name:
        type: string
        description: The name of the tree node.
      children:
        type: array
        items:
          $ref: '#/definitions/TreeNode'

但是,Swagger没有在"children"数组中获取递归引用,该数组简单地显示为"未定义"元素的数组.

有没有人知道如何做到这一点？`

我试图描述的 API 有一个结构，其中根对象可以包含任意数量的子对象（属性本身就是对象）。“键”或根对象中的属性是子对象的唯一标识符，值是子对象的其余数据。

{
  "child1": { ... bunch of stuff ... },
  "child2": { ... bunch of stuff ... },
  ...
}

这可以类似地建模为数组，例如：

[
  { "id": "child1", ... bunch of stuff ... },
  { "id": "child2", ... bunch of stuff ... },
  ...
]

但这既使识别属性在结构上变得不太清楚，并使子代 ID 之间的唯一性隐式而非显式，因此我们想要使用对象或映射。

我已经看过Model with Map/Dictionary Properties的 Swagger 文档，但这并不完全适合我的用例。写一些类似的东西：

"Parent": {
  "additionalProperties": {
    "$ref": "#/components/schemas/Child",
  }

产生这样的东西：

这充分传达了属性中值的描述性，但我如何记录对象中“键”的限制？理想情况下，我想说“这不仅仅是任意字符串，而是与孩子对应的 ID”。这是否以任何方式支持？

我目前正在我的网络中使用Swagger编辑器.编辑器是否有可能直接从git服务器导入文件？

我正在定义一个API,我想在git中使用它,不仅要让它安全,而且要与其他程序员协作.

谢谢你的建议.

我正在构建一组 API 和 webhook。对于常用的 API，我可以毫无问题地编写 YAML 文件来在 Swagger 中记录它。不过，我还想在 Swagger 文档中记录 Webhooks，例如它们的请求正文有效负载以及有关它们的其他信息。

Swagger 中通常如何记录 Webhook 或反向 API？

我正在使用Swagger Edtior为API生成客户端scala代码.我粘贴了json然后做了一个Generate Client/Scala.它给了我一个默认的root包

io.swagger.client

我看不出任何明显的方法来指定不同的东西.可以这样做吗？