标签: swagger-editor

我试图传达认证/安全方案需要设置标题,如下所示:

Authorization: Bearer <token>

这是我基于swagger文档的内容:

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header
security:
  - APIKey: []

提前致谢!

我在Windows 7中使用python 3.5.2版本并尝试使用python3 app.py. 我收到此错误消息

'python3' is not recognized as an internal or external command,
operable program or batch file. 

关于为什么python3命令不起作用的任何具体原因？我还验证了PATH被添加到环境变量中.

我从一些JSON文件创建了一个API规范,我试图测试文件是否根据API规范进行验证.

有一些很好的工具可以验证JSON Schema,但我没有机会找到一个工具来验证Swagger中创建的规范(用于创建API模式的工具).我找到的唯一解决方案是在Swagger-Editor中生成客户端/服务器,这非常麻烦.

是否已有一个现有工具来验证针对Swagger Schema的JSON？

我想格式化我的Swagger API描述,以便它们不是简单的文本段落.最好,我想为它添加一个小桌子.

我没有在Swagger描述中找到有关文本格式的在线参考.如果我启动Swagger编辑器,并打开Instagram示例(File\Open Example\Instagram.yaml),我看到yaml文件中的第一个描述显示了一些格式,包括超链接和边界框:

    [registered your client](http://instagram.com/developer/register/) it's easy
to start requesting data from Instagram.

```
  https://api.instagram.com/v1/media/popular?client_id=CLIENT-ID
```

这看起来像标准的Markdown,但是当我在样本描述中添加表markdown时,编辑器会出现错误:

|Col1|Col2|
|------|------|
|1|2|


YAML Syntax Error
End of the stream or a document separator is expected at line 36, column

Swagger 2.0允许什么格式化？我做错了呈现一张桌子吗？

所以我理解,如果我们想要身体参数,我们必须有一个模式,我这样做.问题是无论我如何尝试定义我的架构,它都不允许我有多个body参数.这是我尝试过的方法之一的示例.任何帮助都会很棒!

swagger: '2.0'

# This is your document metadata
info:
  version: "0.0.1"
  title: Todo App
schema: {
        }
host: localhost:3000
schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/x-www-form-urlencoded
basePath: /

paths:
  # This is a path endpoint. Change it.
  /tasks:
    post:
      description: |
        Add 'Task' object.

      parameters:
        # An example parameter that is in query and is required
        -
          name: name 
          in: query
          description: unique object task name
          required: true
          schema:
            type: string
        - name: description
          in: …

我必须记录我的API.我必须使用其中任何一个Slate或Swagger.我想知道哪一个有更多选择,优点和缺点,哪一个更好.

引用OpenAPI 2.0,模式对象或Swagger 2.0,模式对象以及discriminator字段定义:

添加对多态性的支持.鉴别符是架构属性名称,用于区分继承此架构的其他架构.必须在此模式中定义使用的属性名称,它必须位于required属性列表中.使用时,值必须是此架构的名称或继承它的任何架构.

我的困惑/问题:

• 这对我来说是模棱两可的,它在继承或多态性中起到了什么样的作用.有人可以discriminator用一个工作实例来解释它究竟做了什么以及如果我们不使用它会怎样？某些操作依赖于它的任何错误,警告或任何工具？
• 是不是swagger-editor不支持discriminator,并且这个字段用于其他一些工具？

到目前为止我尝试了什么:

• 我试图使用swagger编辑器和相同文档中的示例(也在下面提到),来玩这个属性,看看我是否可以看到它的任何特殊行为.我更改了属性,删除了它,并将Dog模型扩展到更深层次并在新的子模型上尝试相同,但我没有看到swagger-editor预览中的任何更改.
• 我尝试在线搜索,特别是stackoverflow问题,但没有找到任何相关信息.

我用来做实验的示例代码:

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy …

我正在使用http://editor.swagger.io来设计API,我收到一个错误,我不知道如何解决:

Schema error at paths['/employees/{employeeId}/roles'].get.parameters[0]
should NOT have additional properties
additionalProperty: type, format, name, in, description
Jump to line 24

我有其他端点以类似的方式定义,并没有得到此错误.我想知道我是否有一些缩进或未公开引号的问题,但似乎并非如此.谷歌似乎也没有提供任何有用的结果.

swagger: "2.0"
info:
  description: Initial draft of the API specification
  version: '1.0'
  title: App 4.0 API
host: api.com
basePath: /v1
tags:
  - name: employees
    description: Employee management
schemes:
  - https
paths:
  /employees/{employeeId}/roles:
    get:
      tags:
        - employees
      summary: "Get a specific employee's roles"
      description: ''
      operationId: findEmployeeRoles
      produces:
        - application/json
      parameters:
        - name: employeeId   <====== Line 24
          in: …

我在我的swagger REST API中有一个需要返回pdf文件的调用.没有明确的示例/文档说明如何在不导致语法错误的情况下执行此操作.

  responses:
    200:
      description: Returns PDF
      schema: [application/pdf]

和

  responses:
    200:
      description: Returns PDF
      schema: 
        type: file

和

  responses:
    200:
      description: Returns PDF
      schema:
        type:  [application/pdf]

都失败了.这甚至可能吗？

我正在努力用swagger的语法来描述一个响应类型.我想要建模的是具有动态键和值的哈希映射.这是允许本地化所必需的.语言可能会有所不同,但应始终提供英语.

响应在JSON中看起来像这样:

{
  id: "1234",
  name: {
    en: "english text",
    de: "Deutscher Text"
  }
}

我的第一次尝试看起来像这样,但我不知道如何写这个名称的部分.AdditionalProperties似乎是一个关键,但我无法绕过它.在这种语法中,对英语文本的要求也是一个谜,这个例子似乎也没有按预期工作.它在UI中生成一个空的$ folded:.

delayReason:
  type: object
  properties:
    id:
      type: string
      description: Identifier for a delay reason.
    name:
      type: object
      additionalProperties: 
        type: string
  required: [id, name]
  example:
    id: 123
    name: 
      en: english text
      de: Deutscher Text

但这会产生:

这里也没有任何线索,结果将语言代码作为键,文本作为哈希映射的值.