标签: swagger-editor

我正在尝试使用Swagger 2.0定义API.在我的模型中,我有一些具有可选属性的对象,所以我试图插入Swagger标签"required:false".

当我插入"required"标签时,我在编辑器中收到错误,我无法理解为什么..

我的Swagger定义是:

definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
      message:
        type: string
      fields:
        type: string

这非常有效.现在我想指定'message'参数(例如)是可选的.所以我尝试以下方法:

definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
      message:
        type: string
        required: false
      fields:
        type: string

现在我在Swagger编辑器中出错:

 Swagger Error
Expected type array but found type boolean

错误详情如下:

Details
Object
code: "INVALID_TYPE"
message: "Expected type array but found type boolean"
path: Array [5]
0: "definitions"
1: "Error"
2: "properties"
3: "message"
4: "required"
level: 900
type: "Swagger Error"
description: "Expected type array …

我们当前的部署模式要求我手动编写我的swagger json输出,该输出将由我公司使用的基于Swagger的UI使用.我希望我正在编写的json提供'default'值来填充所有输入字段的Swagger UI,包括body输入参数.我的body参数是一个引用的对象,如下所示.当单击"尝试此操作"时,如何定义返回的swagger JSON以自动填充请求的正文部分？

下面是Swagger UI中没有填充默认/示例数据的示例Swagger规范.

{
   "swagger":"2.0",
   "info":{
      "description":"Example API Description",
      "title":"Example Title",
      "version":"v3.0"
   },
   "tags":[
      {
         "name":"v3"
      }
   ],
   "consumes":[
      "application/json"
   ],
   "produces":[
      "application/json"
   ],
   "paths":{
      "/v3/api/{subscriptionID}/example":{
         "post":{
            "tags":[
               "v3"
            ],
            "description":"This API will do something",
            "consumes":[
               "application/json"
            ],
            "produces":[
               "application/json"
            ],
            "parameters":[
               {
                  "name":"Accept",
                  "in":"header",
                  "description":"The Accept request-header field can be used to specify the media types which are acceptable for the response. If not provided, the default value will be application/json",
                  "required":false,
                  "default":"application/json",
                  "type":"string"
               },
               { …

我正在尝试使用 open api 3 创建一个 swagger 文档，但是当我尝试allOf在参数定义中使用关键字时出现错误

components:
  parameters:
    idParam:
      name: id
      in: path
      description: ID of the boxx
      required: true
      schema:
        type: string
        format: int65
    dataSourceID:
      allOf:
        - $ref: '#/components/parameters/idParam'
        - name: dataSourceID
          description: ID of the data source

components.parameters['dataSourceID'] 处的架构错误

不应该有额外的属性

附加属性：allOf

是否可以重用另一个参数的值？也许以不同的方式？

如何在 swagger 编辑器中指定 3 列，以便输出应如下所示：

ABC
XYZ

a            b            c
x            y            z

我使用swagger-springmvc注释开发了一些由swagger记录的Rest Web服务.现在,我想使用swagger-editor生成客户端Rest Web服务代码,但swagger-editor需要Yaml或Json文件.你知道是否有办法生成这个文件？提前谢谢

编辑: 这可以通过使用swagger-mvn-plugin完成,但我没有找到如何做到的例子？

我试图通过使用allOf. 这是我的 swagger yaml 文件。

swagger: '2.0'
info:
  title: Test API
  version: '1'
basePath: /api/v1
schemes:
  - https
produces:
  - application/json

paths:
  /users:
    get:
      summary: Collection of users
      tags:
        - users
      responses:
        200:
          description: A list of Users
          schema:
            $ref: "#/definitions/Users"        
        500:
          $ref: "#/responses/BadRequest"

definitions:
  User:
    required:
      - username
    properties:
      firstName:
        type: string
      lastName:
        type: string
      username:
        type: string
  Users:
    type: array
    items:
      $ref: "#/definitions/User"

responses:
  NonSuccess:
    description: Generic response for all non-success responses
    schema:
      type: object
      required: …

我正在使用swagger-codegen-maven-plugin基于生成 Java 类swagger.yaml规范。

我phoneNum在swagger.yaml下面添加了一个属性：

phoneNum:
    type: number

我期望它生成带有Integer或Long数据类型的属性。
但它生成为BigDecimal phoneNum;

根据swagger 文档，有人提到使用format: int64

  phoneNum:
    type: number
    format: int64

但是，它最终会产生 private BigDecimal phoneNum;

如果你们中有人遇到过类似的问题并有解决方法，请在此处分享。

谢谢你。

我正在使用 Swagger Hub 生成 API，并希望获得 get 请求的多个响应：https://virtserver.swaggerhub.com/factly/test/1.0.0/categories

以下是我定义 API 的方式。当我执行 API 时，我只得到一个类别的响应。如何将所有三个类别定义为响应？任何帮助是极大的赞赏。

openapi: 3.0.0
info:
  description: This is the sample API for Core
  version: "1.0.0"
  title: Dega Core API
tags:
  - name: Core
    description: Operations related to Core
paths:
  /categories:
    get:
      tags:
        - Core
      summary: gets all the categories
      description: this is to get all the available categories
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryItem'
              examples:
                category1:
                  $ref: '#/components/examples/category1'
                category2:
                  $ref: '#/components/examples/category2' 
                category3:
                  $ref: …

有没有可以让我从示例JSON生成Swagger Yaml定义模型的工具？

我会去编辑和清理Yaml，但是如果有一些东西会根据大型或复杂的json对象存根Yaml的结构，那就太好了。

以下 YAML：

openapi: 3.0.0
info:
  title: test
  version: 1.0.0
paths:
  /test:
    get:
      summary: test
      responses:
        '200':
          description: Test
          content:
            application/json:
              schema:
                oneOf:
                  - allOf:
                    - type: object
                      properties:
                        firstA:
                          type: string
                    - type: object
                      properties:
                        firstB:
                          type: string
                  - allOf:
                    - type: object
                      properties:
                        secondA:
                          type: string
                    - type: object
                      properties:
                        secondB:
                          type: string

在swagger 编辑器中根本不渲染。

在ReDoc中它也无法正确渲染：

如果allOf直接在其中嵌套多个实例oneOf是无效的，我如何使用有效的规范获得相同的结果？

我在以下 OpenAPI 定义的 Swagger 编辑器中收到“映射条目缩进错误”错误。谁能告诉下面的代码有什么问题？

      responses:
        '200':
          description: List all applicable errors for API
          headers:
            x-request-received-at:
              type: string
              description: A datetime stamp of when the request was received
            x-response-sent-at:
              type: string
              description: A datetime stamp of when the response was sent
          schema:
            $ref: '#/definitions/ErrorResponse'
        default:
          description: An unexpected error occurred
          schema:
            $ref: '#/definitions/Error'
   '/funeral/{contractReference}/agreement':
     get:
        summary: Get the funeral policy and debit order mandate agreement for the client to sign
        operationId: 
         - get801FuneralCoverPlanAgreementHtml
         - getAUTHORITYANDMANDATEFORPAYMENTINSTRUCTIONSHTML
        tags:
         - "FuneralCoverService"
         - "InternalAPI" …

我正在使用 OpenAPI定义（小部分）现有 API ( Samanage ) 以协助一些集成工作。

我需要使用 Bearer auth 进行身份验证，但通过在Authorize.

服务器期望在一个X-Samanage-Authorization像这个例子一样命名的标头中进行承载身份验证：

curl -H "X-Samanage-Authorization: Bearer <TokenGoesHere>" -H 'Accept: application/vnd.samanage.v2.1+json' -H 'Content-Type: application/json' -X GET https://api.samanage.com/incidents.json

我知道https://swagger.io/docs/specification/authentication/bearer-authentication/，但它似乎并没有完全帮助我。

这（OpenAPI 3）

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
...
security:
- bearerAuth: []

生成名为 default ( Authorization)的身份验证标头

curl -X GET "https://api.samanage.com/incidents/12341234.json" -H "accept: application/json" -H "Authorization: Bearer <TokenGoesHere>"

然后失败（401）。

我觉得我想要这个：

components:
  securitySchemes:
    bearerAuth:
      type: http
      name: X-Samanage-Authorization
      in: header
      scheme: bearer

但这在 Swagger …

我收到以下错误：

声明的路径参数“imageId”需要在路径或操作级别定义为路径参数

这是我的招摇定义的快照

 '/api/v1/images/{unitnumber}/{type}/{imageId}':
        delete:
          tags:
            - Images
          summary: 'Summary'
          description: "Description"
          operationId: DeleteImage
          consumes: []
          produces:
            - application/json
          parameters:
            - name: unitnumber
              in: path
              required: true
              type: string
            - name: type
              in: path
              required: true
              type: string
            - name: imageId
              in: query
              required: false
              type: string
          responses:
            '400':
              description: Bad Request
              schema:
                $ref: '#/definitions/ErrorResponse'
            '401':
              description: Unauthorized
              schema:
                type: string
            '500':
              description: Server Error
              schema:
                $ref: '#/definitions/ErrorResponse'

我只可以摆脱错误的，如果我走了imageId，改变以path代替query其意向不大

           - name: imageId
                  in: path …