标签: swagger-editor

作为我们持续交付管道的一部分,我将部署AWS API Gateway API.

最简单的方法是使用Amazon API Gateway Importer,它可以从Swagger表示创建或更新Amazon API Gateway API.

AWS为Swagger提供API网关扩展.通过这些扩展,您可以在Swagger定义中提供请求/响应模板.下面是一个带有Swagger API网关扩展的json片段示例:

"x-amazon-apigateway-integration": {
      "responses": {
        "default": {
          "statusCode": "200",
          "responseParameters": {
            "method.response.header.Access-Control-Allow-Origin": "'*'"
          },
          "responseTemplates": {
            "application/json": "#set($inputRoot = $input.path('$'))\r\n[\r\n#foreach($elem in $inputRoot)\r\n    {\r\n      \"id\" : \"$elem.id\",\r\n      \"login\" : \"$elem.login\"\r\n    }#if($foreach.hasNext),#end\r\n        \r\n#end\r\n  ]\r\n"
          }
        }
      },
      "uri": "http://www.example.com/api/users",
      "httpMethod": "GET",
      "requestParameters": {
        "integration.request.querystring.page": "method.request.querystring.page",
        "integration.request.header.x-auth-token": "method.request.header.x-auth-token",
        "integration.request.querystring.size": "method.request.querystring.size"
      },
      "type": "http"
    }
  }

编辑Swagger定义变得容易出错,因为您需要内联AWS API网关模板.

Swagger网站列出了许多用于从Swagger定义生成客户端/服务器存根或从API代码生成Swagger定义的工具.

我正在寻找类似于对流层的工具.我的想法是我可以用Python定义我的API,然后生成一个JSON或yaml文件.好处是我可以分离AWS API网关请求/响应模板,然后将它们拉入生成的Swagger定义中.

有谁知道任何有用的工具？

如何允许用户在 swagger 中输入客户端 ID 和客户端密码？这是我的安全定义，但它提示通过 client_id 和客户端机密获得的访问令牌，但我无法让它询问客户端 ID 和客户端机密？

securityDefinitions:
  api_auth :
  type: oauth2
  authorizationUrl: 'https://randomapi/aa/token.oauth2'
  flow: implicit
  scopes:

我正在尝试使用 swagger 在线编辑器http://editor.swagger.io/#/

有一个名为 Authorize 的按钮可打开一个对话框，您可以在其中提供授权方法。有两种选择

第一个用于 OAuth2，第二个用于 API-Key。

我无法弄清楚如何使用这些。

• 对于 OAuth2 授权，需要一个客户端 ID。如何获得客户端 ID？
• 对于 api-key 授权，编辑器提供了一个名为 special-key 的密钥。当我在 postman 中没有特殊键的情况下进行 API 调用时，API 会返回有效的响应。这是因为实现也没有密钥吗？

下面这个错误是什么意思？（在 Swagger 编辑器中运行）

架构错误不应具有附加属性 additionalProperty: /buildinfo, /clearcache, /countries/{countryId}/cinemas/{theatreid}/screens/{screenid}/layout, /countries/{countryId}/cinemas/{theatreid}/screens跳到第 0 行

下面是我的 yaml 文件。

openapi: "3.0.1"
info:
  title: Mobile backend
  version: 1.0.0
  license:
    name: Apache 2.0
paths:
/buildinfo:
    get:
      description: Returns the build information (Version and Time stamp).
      operationId: getBuildInfo
      parameters:
        - name: LBPATH
          in: header
/clearcache:
    get:
      description: Clears the mobile backends cache (You need to be Admin to do this call)
      operationId: clearCache
      parameters:
        - name: LBPATH
          in: header
/countries/{countryId}/cinemas/{theatreid}/screens/{screenid}/layout:
    get:
      description: Returns a list of Auditoriums that …

我在 OpenAPI 3.0 中使用 Swagger 编辑器。我需要记录一条包含上传图像的路线。尝试“试用”时，我没有让文件浏览器选择要在请求正文中上传的图像，我得到的只是一个带有参数名称和类型的 JSON 字符串。

这是路由的 YAML 描述：

openapi: 3.0.0
...
paths:
  /media/upload/thumbnail:
    post:
      tags:
        - media
        - publications
      security:
        - bearerAuth: []
      summary: upload a kid's publication
      operationId: uploadPublication
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upload:
                  type: string
                  format: binary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: ObjectId of the uploaded file in db (original size)
                    example: 5a6048b3fad06019afe44f24
                  filename:
                    type: string
                    example: myPainting.png
                  thumbnail:
                    type: string
                    description: …

我在我的机器上本地使用 Swagger 编辑器。

当我启动 Swagger Editor 时，它在启动时默认显示 petstore 的规范。

我想删除它并显示一个空白的编辑器。有没有办法在启动时做到这一点。

我是 swagger 的新手，我一直在尝试使用 swagger-editor 开发 api。

Swagger-codegen 表示这是一个开源代码生成器，可以直接从 Swagger 定义的 RESTful API 构建服务器存根和客户端 SDK。

当我使用 swagger-editor 时，我可以看到选项：生成服务器和生成客户端（我在本地运行 swagger-editor）

swagger-codegen 是否具有与 swagger-editor 中的 Generate server 和 Generate Client 相同的功能，或者还有其他功能吗？

提前致谢。

我在为 OpenAPI (Swagger) 文档定义自定义请求标头时遇到问题。我查看了文档https://swagger.io/docs/specification/describing-parameters/#header-parameters但我无法让它工作。

在我下面的示例中，是一个具有正文的 POST 请求。我还希望它有一个像我的第二个片段一样的自定义标头，但这无效。

还行吧：

 /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

这是不行的：

  /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
       - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          required: true …

我正在尝试使用 json 正文的示例来记录 api 错误响应。我找不到示例或合适的注释。使用 swagger 编辑器，我至少可以获得一些看起来像我想要实现的结果的东西。

responses:
    '200' :
      description: Request completed with no errors
      examples:   
        application/json:  {"result" : { "id": "blue" }}

库是 swagger-core 1.6.0

 <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <scope>compile</scope>
            <version>1.6.0</version>
</dependency>

端点是使用 jax-rs 创建的。

我对端点做了这个

@ApiResponses(value = {
    @ApiResponse(code = 200, message = "OK",
            examples = @Example(value = @ExampleProperty(mediaType = "application/json", value = "{\"result\" : { \"id\": \"blue\" }}"))
    )
})
public Response getResult(){}   

生成的 swagger.json 没有所需的

examples:   
 application/json:  {"result" : { "id": "blue" }}         

我也尝试传递response = ApiResponse.class、Examples.class和Example.class，但它没有改变。 …

我正在尝试记录一个始终返回自定义响应代码和相关描述的模型。对于单个 HTTP 响应代码，可能有多个自定义响应代码。例如，400 响应可能包括：

+===========+======+=============+
| HTTP Code | Code | Description |
+===========+======+=============+
|       400 |    1 | Error 1     |
+-----------+------+-------------+
|       400 |    2 | Error 2     |
+-----------+------+-------------+
|       400 |    3 | Error 3     |
+-----------+------+-------------+

我可以记录 400 状态返回一个具有“代码”和“描述”的“错误”对象。但如果可能的话，我想在文档中包含所有自定义状态代码。是否可以？如果是这样，我将如何去做？