标签: swagger-editor

我正在尝试将Atom发布协议(RFC5023)转换为Swagger/OpenAPI规范来练习编写这些规范.

我遇到了以下问题:在Atom中有不同类型的URI,例如Collection和Member URI.我的想法是这样记录:

paths:
  /{CollectionURI}:
    get:
      summary: List Collection Members
      ...
    post:
      summary: Create a Resource
      ...
    parameters:
      - $ref: "#/parameters/CollectionURI"
  /{MemberURI}:
    get:
      summary: Retrieve a Resource
      ...
    parameters:
      - $ref: "#/parameters/MemberURI"

当我这样做时,swagger-editor声称这样做

已存在等效路径:/ {MemberURI}

这些是在查询时返回不同内容的不同类型的URI.我想以不同方式调用它们来单独记录它们.

有没有办法做到这一点？

谢谢!

编辑:规格在Swagger-UI中显示得很好 - 这是编辑器中的错误还是UI只是忽略了我的错误？

我在我的工作区内的根目录中创建了新项目(nodeJS),一段时间后我想将项目的客户端和服务器端分开.为此,我在项目的根目录中创建了两个文件夹(服务器和客户端),并将所有文件和目录移动到适当的文件夹.

之后我无法启动服务器,因为它说Swagger无法找到swagger.yaml文件(我将其移动到服务器文件夹)

{ Error: ENOENT: no such file or directory, open 'C:\Users\User\Documents\movieCollection\api\swagger\swagger.yaml'
    at Error (native)
    at Object.fs.openSync (fs.js:634:18)
    at Object.fs.readFileSync (fs.js:502:33)
    at C:\Users\User\AppData\Roaming\npm\node_modules\swagger\lib\commands\project\project.js:283:44
    at findProjectFile (C:\Users\User\AppData\Roaming\npm\node_modules\swagger\lib\commands\project\project.js:308:14)
    at readProject (C:\Users\User\AppData\Roaming\npm\node_modules\swagger\lib\commands\project\project.js:268:3)
    at Command.edit (C:\Users\User\AppData\Roaming\npm\node_modules\swagger\lib\commands\project\project.js:240:3)
    at Command.<anonymous> (C:\Users\User\AppData\Roaming\npm\node_modules\swagger\lib\util\cli.js:167:27)
    at Command.listener (C:\Users\User\AppData\Roaming\npm\node_modules\swagger\node_modules\commander\index.js:301:8)
    at emitTwo (events.js:106:13)
  errno: -4058,
  code: 'ENOENT',
  syscall: 'open',
  path: 'C:\\Users\\User\\Documents\\movieCollection\\api\\swagger\\swagger.yaml' }

我试图编辑节点服务器的config文件夹中的default.yaml文件,但问题仍然存在.

有没有办法将swagger项目配置指向新的laction(目录 - >服务器文件夹)？

default.yaml:

# swagger configuration file

# values in the swagger hash are system configuration for swagger-node
swagger:

  fittingsDirs: [ api/fittings …

我无法在对象定义中找到货币数据类型的样本,也找不到有关该主题的文档.

我正在尝试创建 swagger json 并尝试在http://editor.swagger.io 中检查它的有效性

验证json后，上面提到的编辑器给出了以下错误：

Schema error should NOT have additional properties
additionalProperty: components
Jump to line 0

如果由于某种原因我无法在根级别定义一个名为 components 的元素，我将在其中拥有某种 json 模式，那么按照我的意图对 requestBody 的模式执行 $ref 的正确方法是什么如下例所示。另外，你看到我的 swagger json 有什么问题吗？

我的 swagger2.0 的 swagger json 看起来像这样。

{
    "swagger": "2.0",
    "info": {
        "version": "1.0",
        "title": "My swagger API",
        "contact": {
            "name": "myName",
            "email": "abc@gmail.com"
        }
    },
    "host": "localhost:1234",
    "basePath": "/",
    "tags": [{
        "name": "someTagName",
        "description": "this is a try"
    }],
    "components":{"schemas": {"myEndPoint": ""}},
    "paths": {
        "/myEndPoint": {
            "post": …

我正在尝试为 Webcase Create 会议创建 OpenAPI 定义。这是我的 YAML 代码：

openapi: '3.0.0'
info:
  title: WebcastCreateMeeting
  version: "1.1"
servers:
  - url: https://api.webcasts.com/api
paths:
  '/event/create':
    post:
      tags:
       - CreateMeetingCallbody
      summary: EventGM
      parameters:  
        - in: path
          name: event_title                        # >> line 15
          description: name of the event from Cvent
          required: true
          schema:
            type: string
      responses:
        200:
          description: This would be the response.
          content:
            application/json;charset=utf-8:
              schema:
                type: array
                items:
                  properties:
                    scheduled_duration:
                      type: integer
                      example: 30
                    event_id:
                      type: integer
                      example: 0000000
                    event_title:
                     type: string
                     example: Cvent Testing …

我正在尝试使用静态swagger文件来记录API,该文件可以返回一些包含类似于以下内容的数组的JSON:

[
  {
    "type": "type A",
    "field A": "this field is specific to type A"
  },
  {
    "type": "type B",
    "field B": "this field is specific to type B"
  }
]

我尝试了几种使用多态或明确定义多个示例来定义规范的方法.这些例子总是看起来像:

[
  {
    "type": "type A",
    "field A": "this field is specific to type A",
    "field B": "this field is specific to type B"
  }
]

要不就:

[
  {
    "type": "type A",
    "field A": "this field is specific to type A"
  }
]

有没有办法在我的swagger规范中定义一个示例,以便swagger-ui显示的示例有效负载将包含一个包含Type A示例的数组和一个B类示例,就像我写的第一个JSON一样？

我的任务是将Swagger安装到Web API项目中.

安装:来自nuget的最新版Swashbuckle.(Swashbuckle.Core.Net45和Swashbuckle.Net45)

自定义:App_Start\SwaggerConfig.cs.我能够自定义(更改样式,添加徽标,修改说明)..

现在我们需要从https:// [your-url]/swagger更改为https:// [your-url]/help

请指教

我正在寻找一种优雅的方式来定义可以使用 JSON 数据和表单数据的 api。以下代码段有效，但它并不优雅，并且需要在后端使用各种丑陋的代码。有没有更好的方法来定义这个？

现在什么工作：

paths:
  /pets:
    post:
      consumes:
      - application/x-www-form-urlencoded
      - application/json
      parameters:
      - name: nameFormData
        in: formData
        description: Updated name of the pet
        required: false
        type: string
      - name: nameJSON
        in: body
        description: Updated name of the pet
        required: false
        type: string

我希望它如何工作的基本想法：

paths:
  /pets:
    post:
      consumes:
      - application/x-www-form-urlencoded
      - application/json
      parameters:
      - name: name
        in: 
        - formData
        - body
        description: Updated name of the pet
        required: true
        type: string

但这不起作用，因为该in值必须是字符串，而不是数组。

有什么好主意吗？

我想在我的API描述中放一个Markdown代码块，但是Swagger UI似乎正在读取，好像它是一个单行代码片段一样。我目前有：

description: |
    This API was created to allow interaction with the Image Status Database (ISD)

    ## Requests

    ## Responses
    In the case of a successful response, you will always receive a `data` key
    that contains your data.
    ```
    {
        "meta": {
            "code": 200
        },
        "data": {
            ...
        },
        "pagination": {
            "next_url": "...",
            "next_max_id": "13872296"
        }
    }
    ```

显示为：

但是，Swagger编辑器显示正确的代码块：

Swagger UI不支持此功能吗？

我正在为需要非常详细和干净的文档的未来公共 API 编写 Swagger 规范。有没有办法在swagger.yml文件中的其他位置引用/链接/指向另一个端点？

例如，这是我想要实现的目标：

paths:
  /my/endpoint:
    post:
      tags:
        - Some tag
      summary: Do things
      description: >
        This endpoint does things.
        See /my/otherEndpoint for stuff  # Here I would like to have some kind of hyperlink
      operationId: doThings
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        ...
      responses:
        ...
  /my/otherEndpoint:  # This is the endpoint to be referenced to
    get:
      ...

我发现这$ref无济于事，因为它只是用引用的内容替换了自己。

Swagger 可以做这样的事情吗？