标签: openapi

我想用 OpenAPI 2.0 (Swagger 2.0) 描述 RESTful 接口的 XML 响应负载。但是，我很难在 OpenAPI 数据模型中描述特定的 XML 标记。

我无法让 Swagger UI 以这种形式创建适当的示例 XML 标签，在开始和结束 XML 标签之间有一个属性和内容：

<Person id="bar">foo</Person>

文档（此处）仅描述了如何为带有子标签 ( type: object) 的标签或带有内容 ( type: string)的标签建模，但不能同时为两者建模。

我试过这个，Swagger 编辑器接受它，没有任何错误或警告：

<Person id="bar">foo</Person>

但它将由 Swagger UI 呈现为以下示例：

<Person id="bar"></Person>

如您所见，其中没有“foo”内容。

使用editor.swagger.io设计API 我发现自己无法添加requestBody属性,收到我无法解决的错误:

Schema error at paths['/projects/{projectId}/user'].post
should NOT have additional properties
additionalProperty: requestBody
Jump to line 91

我不明白我做错了什么,特别是在查看requestBody文档之后.研究给我带来的只是误差误导的倾向.

编辑:从这里的答案显示,看起来编辑器应该使用OpenAPI 2.0,但实际上期望3.0同时返回两者的错误.鉴于我已经包含了一个,我会在使用什么方面使用一些帮助

swagger: "2.0"

在文档开头的行.虽然与测试openapi: 3.0.0作为他的回答所示@Mike,我只是得到关于允许附加属性更多的错误.

这就是产生错误的原因,第91行post:.

/projects/{projectId}/user:
      post:
        tags:
        - projects
        summary: Modify project user.
        operationId: modifyProjectUser
        parameters:
        - name: projectId
          in: path
          description: ID of the project
          required: true
          type: integer
          format: int32
        requestBody:
          content: 
            application/json:
              schema:
              $ref: '#/definitions/User'
        responses:
          "200":
            description: Successful operation
            schema:
              type: array
              items:
                $ref: "#/definitions/User"
        security:
        - …

按规格：

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

规范使用的带有附加元数据的标签列表。标签的顺序可以被解析工具用来反映它们的顺序。并非操作对象使用的所有标记都必须声明。未声明的标签可以随机组织或基于工具的逻辑。列表中的每个标签名称必须是唯一的。

这些标签在解析器中是如何使用的，你能提供一些例子吗？还有为什么需要是独一无二的？

我正在尝试生成数据以填充我的代码库中的 OpenAPI 3.0 输入。

我有一个用于将文件上传到服务器的休息端点。

我有一个表单作为聚合物 vaadin-upload 组件用于上传文件。路径为/upload-all，表单参数名称为my-attachment。该表单正确地将文件上传到服务器，因此这不是问题。

服务器端点是使用HTML 表单规范中的 XQRS RestXQ 上传文件来实现的。

我正在尝试为 OpenAPI 3.0 UI 创建 OpenAPI JSON 输入以进行分段文件上传。这是我尝试过的：

"/upload-all": {
    "post": {
        "consumes": ["multipart/form-data"],
        "description": "Upload zip file to the server",
        "responses": {
            "content": {
                "application/json": {
                    "schema": {
                        "type": "object"
                    }
                }
            }
        },
        "parameters": [
            {
                "in": "formData",
                "schema": {
                    "type": "array",
                    "items": {
                        "type": "file"
                    }
                },
                "name": "my-attachment"
            }
        ]
    }
},

我收到一个错误，提示表单参数my-attachment未填充。我缺少什么？我在 OpenAPI 网站上找不到明确的规范。 …

我试图仅使用 OpenApi 及其 maven 插件openapi-generator-maven-plugin生成接口，但它也生成我不想要/不需要的完整服务。

现在我找到了withInterfaces属性，但当设置为 true 时，它​​还会生成 API 服务。因此它会生成我想要的服务，但也会生成我不想要的服务。

这是我的 pom 配置：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>3.3.4</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${openAPIContractsDirectory}/swagger.json</inputSpec>
                <generatorName>typescript-angular</generatorName>
                <output>${openAPIOutputDirectory}</output>
                <configOptions>
                    <ngVersion>7.2.11</ngVersion>
                    <withInterfaces>true</withInterfaces>
                </configOptions>
                <generateApiTests>false</generateApiTests>
                <generateApiDocumentation>false</generateApiDocumentation>
                <generateModelTests>false</generateModelTests>
                <generateModelDocumentation>false</generateModelDocumentation>
                <supportingFilesToGenerate>variables.ts,configuration.ts,encoder.ts</supportingFilesToGenerate>
            </configuration>
        </execution>
    </executions>
</plugin>

我想要的是模型、pom 中描述的一些支持文件，以及API 接口（不是完整的服务）。

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

我试图实现一个 OpenAPI 定义，其中我将允许值的共享、完整列表定义为枚举，然后在不同位置使用值的子组来显示每种情况下允许哪些值。

使用Swagger.io 上枚举规范的示例，如果我有这样的定义：

paths:
  /products:
    get:
      parameters:
      - in: query
        name: color
        required: true
        schema:
          $ref: '#/components/schemas/Color'
      responses:
        '200':
          description: OK
components:
  schemas:
    Color:
      type: string
      enum:
        - black
        - white
        - red
        - green
        - blue

那么是否可以定义例如两个以颜色作为参数的不同路径，但其中一个仅接受black或white另一个接受所有颜色？

我在 SwaggerHub 注册并使用 OpenAPI 3.0 创建了一个新的 API。在我的 API 中，/tasks路径有 2 个非必需参数，但我无法将它们设置为非必需 - 编辑器显示“不允许的值”错误。

这是我的 API 定义：

openapi: 3.0.0
info:
  description: A Simple IP Address API
  title: VTasks
  version: v1
servers:
# Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/petrogromovo/Vtasks/1.0.0
  - description: SwaggerHub API Auto Mocking
    url: http://hosting.tk

paths:

  /tasks:
    get:
      tags:
        - tasks
      summary: Get paginated / filtered tasks listing
      operationId: tasks
      parameters:
        - name: page
          in: path
          description: The page number …

我有 Springboot 项目，我想在其中记录我的 API：

这是正在处理的 Web 服务的示例：

    @ApiResponses(
        value = {
                @ApiResponse(responseCode = "200", content =  @Content(
                        mediaType = "*/*",
                        schema = @Schema(implementation = Object.class),
                        examples = {
                                @ExampleObject(name = "boo",
                                summary = "example of boo",
                                ref = "#/swagger/Planner/semi_planif_200_response.json")
                        }

                ))
        }
)
@PostMapping(value = "/startSemiPlanification", produces = "application/json")
private ResponseEntity<Object> startSemiPlanner( @RequestBody PlanificationDto planificationData,
                                                @RequestParam(name = "groupByUserCode", required = false) Optional<Boolean> groupByUserCode,
                                            @RequestParam(name = "range", defaultValue = "18") Integer range

我的问题是 Swagger 无法解析此引用 ref = "#/swagger/Planner/semi_planif_200_response.json" 我什至尝试过使用绝对路径，但它不起作用：

这是文件路径：

我的 openapi 合约中有以下模式定义来表示commission amount。

commissionAmount:
  type: number
  minimum: -99999.99
  maximum: 99999.99

生成的代码：

@Valid
@DecimalMin("-99999.99") @DecimalMax("99999.99") 
public BigDecimal getCommissionAmount() {
  return commAmt;
}

生成的代码很好并且符合预期。我只是想知道这些-99999.99以及和99999.99的有效值。minimummaximum

提出这个问题的原因是它没有检查小数部分的限制。例如，我期望12345.678is invalid ，12345.67is valid 。但它将两者标记为有效。

I read@Digits用于检查整数和小数部分的位数限制。我如何告诉也openapi-generator-maven-plugin进行注释？Digits

预期生成的代码：

@Valid
@Digits(integer = 5, fraction = 2)
@DecimalMin("-99999.99") @DecimalMax("99999.99") 
public BigDecimal getCommissionAmount() {
  return commAmt;
}

我已成功从 .yaml open-api 描述符文件生成接口，但是，如问题标题所示，我希望将这些接口的响应类型从 ResponseEntity 更改为我自己的类型。基本上而不是具有此签名的接口：

 ResponseEntity<Void> clearCache();

对于基本上以这种方式实现的方法：

public void clearCache(){ //do something}

我希望生成的界面就像

void clearCache();

对于我自己定义的类来说也是如此，而不是ResponseEntity<MyBook> getBook(String ISBN);我希望它只用作MyBook返回类型，所以它应该看起来像MyBook getBook(String ISBN); 我用于 openapi-generator 插件的当前设置是

        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>4.3.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration>
                        <inputSpec>my-own-service-be/src/main/resources/api-docs.yaml</inputSpec>
                        <generatorName>spring</generatorName>
                        <additionalProperties>
                             <additionalProperty>skipDefaultInterface=true</additionalProperty>
                            <additionalProperty>interfaceOnly=true</additionalProperty>
                        </additionalProperties>
                        <generateApis>true</generateApis>
                        <apiPackage>controller</apiPackage>
                        <supportingFilesToGenerate>false</supportingFilesToGenerate>
                        <modelPackage>dto</modelPackage>
                        <generateModelTests>false</generateModelTests>
                        <generateApiTests>false</generateApiTests>
                    </configuration>
                </execution>
            </executions>
        </plugin>