标签: openapi

我想使用 Mapstruct 将内部模型映射到 Kotlin 项目中由 OpenApi3 codegen 生成的模型。

当我编译项目时，Mapstruct 似乎无法找到 OpenApi3 codegen 插件生成的源，因为生成的实现包含 aNonExistentClass而不是我的 OpenApi 模型。

我的插件配置是

<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-maven-plugin</artifactId>
    <configuration>
        <args>
            <arg>-Xjsr305=strict</arg>
        </args>
        <compilerPlugins>
            <plugin>spring</plugin>
            <plugin>jpa</plugin>
        </compilerPlugins>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-allopen</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-noarg</artifactId>
            <version>${kotlin.version}</version>
        </dependency>
    </dependencies>

    <executions>
        <execution>
            <id>kapt</id>
            <phase>process-sources</phase>
            <goals>
                <goal>kapt</goal>
            </goals>
            <configuration>
                <sourceDirs>
                    <sourceDir>src/main/kotlin</sourceDir>
                    <sourceDir>src/main/java</sourceDir>
                </sourceDirs>
                <annotationProcessorPaths>
                    <annotationProcessorPath>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </annotationProcessorPath>
                </annotationProcessorPaths>
            </configuration>
        </execution>

        <execution>
            <id>compile</id>
            <phase>process-sources</phase>
            <goals>
                <goal>compile</goal>
            </goals>
        </execution>
        <execution>
            <id>test-compile</id>
            <phase>process-test-sources</phase>
            <goals>
                <goal>test-compile</goal>
            </goals>
        </execution>

    </executions>
</plugin> …

我正在构建一个简单的 OpenAPI 3 YAML 规范，如下所示：

paths:
  /query:
    get:
      parameters:
        - $ref: '#/components/parameters/bookid'

components:
  parameters:
    bookid:
      in: query
      name: bookid
      required: false
      schema:
        format: integer
        type: number    

现在，我想使用通用bookid 参数，但覆盖to 的required值。例如（这不起作用！！！）：falsetrue

paths:
  ...

  /query2:
    get:
      parameters:
        - $ref: '#/components/parameters/bookid'
          required: true  # <--- ???

有没有办法做到这一点？

我尝试使用 swagger 创建有关现有 API 的文档，但是当我使用 openapi 时，此错误：无法读取未定义的属性 \'get\' 会显示到控制台中。

这个错误只是在我使用时发生openapi: "3.0.0"

app.js代码：

const swaggerUi     = require(\'swagger-ui-express\'), swaggerDocument = require(\'./swagger.json\');\nconst swaggerJsdoc  = require(\'swagger-jsdoc\');\nconst express       = require(\'express\');\nconst cors          = require(\'cors\');\nconst bodyParser    = require(\'body-parser\');\nconst handlebars    = require(\'express-handlebars\');\nconst helmet        = require(\'helmet\');\n\nconst app = express();//Here define app for create a middlewares using app.use();\n\nconst swaggerOptions = {\n    swaggerDefinition: {\n        info: {\n          title: \'\xc3\x81gil API\',\n          version: \'1.0.0\',\n          description: \'Document API with autogenerated swagger doc\',\n        },\n        host: \'localhost:3000\',\n        basePath: \'/\',\n        components: {\n            securitySchemes: {\n …

我正在尝试为我的 Java 代码生成 OpenAPI（版本 3.0.1）规范。为了实现这一点，我使用 Swagger Annotations（版本 2.0.8）和 Swagger Maven 插件。

我对枚举有疑问。比如说，我有两个方法返回完全相同的枚举。在 OpenAPI 规范中，我希望有这个 Enum 的单一模式定义，并且$ref在两个 API 操作中都有此枚举和链接的单一架构定义。但我在每个 API 操作中都有重复的 Enum 定义。如何在不手动编辑规范文件的情况下避免这种重复？

下面是 Java 代码，其中两个方法返回相同的 Enum：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

@Path("/properties")
@Produces("application/json")
public class TestService {
    @GET
    @Path("/enum1")
    @Operation
    @ApiResponses({
        @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = Color.class)))
    })
    public Color getColor1() {
        throw new UnsupportedOperationException();
    }

    @GET
    @Path("/enum2")
    @Operation
    @ApiResponses({
        @ApiResponse(responseCode = "200", …

我有根据jsonapi.org指南构建的 HTTP 请求负载：

{
  "data": {
    "type": "employee",
    "attributes": {
      "firstName": "John",
      "lastName": "Doe",
    }
  }
}

然后我有这个有效负载的OpenApi规范 (yaml)：

employee: 
  type: object
  required: [data]
  properties:
    data:
      type: object
      properties:
        type:
          type: string
          enum: [employee]
        attributes: 
          type: object
          required: [firstName, lastName]
          properties:
            firstName:
              type: string
              example: 'John'
            lastName:
              type: string
              example: 'Doe'

我想要的是根据规范（来自 Ruby/Rails）验证有效负载。

存在openapi3_parser gem，但它似乎只能验证规范，而不能验证实际的有效负载。

然后，还有jsonapi.org 有效负载反序列化器，但它们似乎根本不关心 OpenApi 正式规范。

我使用 OpenApi 来描述有效负载，因为我通过 Swagger 免费获得 http API 文档。

在我的控制器方法之一中，我尝试添加这样的注释：

 *     @OA\Response(
 *         response="404",
 *         description="Invalid field"
 *     ),
 *     @OA\Response(
 *         response="404",
 *         description="Entity not found"
 *     )

但现在当我尝试构建文档时，我从 openapi 收到一条错误消息：

Warning: Multiple @OA\Response() with the same response="400":

我知道现在有一个oneOf大摇大摆的出现，看来正是为了我的目的。但是，我不知道如何使用它。

我正在尝试使用 OpenAPI 3、YAML 来构建 API 定义。我一直在使用文档https://swagger.io/docs/specation/adding-examples/了解如何添加示例。

在我的 API 定义中，我有一个返回 JSON 数组的端点。我已经成功地让这个示例作为 API 定义的一部分工作，但现在我试图提取该示例并将其移动到参考资料部分components，但我没有任何运气。

这是我目前拥有的：

paths: 
  /report:
    get:
      parameters: 
        - in: query
          name: dateFrom
          schema:
            type: string
            format: date
          required: true
          example: "2020-01-21"
          description: The start date range
        - in: query
          name: dateTo
          schema:
            type: string
            format: date
          required: true
          example: "2020-02-01"
          description: The end date range
      summary: Used by Anayltics to produce reports showing submission that cannot be determined by GA
      responses:
        '200':
          description: valid response …

我正在为一个项目设计一个 openAPI 规范。该项目是一个提供有关酒店信息的 REST API。

我想提供有关酒店的详细信息或快速摘要。我对 REST 的理解是，由于这两者都与我的数据存储中的同一对象相关，因此我应该使用查询参数来请求不同的数据类型。

因此，我正在寻找一种根据给定请求的查询参数指定不同 API 行为的方法。这是我当前的实现。我正在寻找这样的端点：

/hotels/{hotelId}?detail={detailLevel}

其中{hotelId}是一个整数，{detailLevel}是一个可选的字符串枚举，可以是summary或robust。

如果detail=robust，响应应如下所示：

{
  "name": "Hilton Grand Vacations on the Las Vegas Strip"
  "streetAddress": "2650 Las Vegas Blvd S",
  "city": "Las Vegas",
  "state": "NV",
  "zipCode": 89109
  "rating": 4.4,
  "minimumPrice": 125,
  "availableRooms": 10,
}

如果detail=summary，响应应如下所示：

{
  "name": "Hilton Grand Vacations on the Las Vegas Strip",
  "rating": 4,
  "zipCode": 89109,
  "available": true
}

我不想有一个涵盖这两个响应的规范，因为我希望能够轻松地根据其 URL 参数验证任何给定的响应（例如，"available"不应该是一个字段 when …

我正在查看 OAS，可以看到它在哪里列出了推荐的文件名，但openapi.json我有两个问题：

1. 显然没有一个标准的放置位置，但是否存在人们似乎遵循的事实上的标准？就像假设最“正常”的地方使它可以访问/openapi.json？

2. 为什么这被排除在规范之外，为什么甚至只是推荐而不是必需的文档名称？这样做的部分目的不就是让它被发现吗？似乎重新定位 OpenAPI 文档可以通过给你一些你必须知道的东西来减少这一点。忽略它有什么好处吗？

我正在尝试在在线 Swagger 编辑器中的用户类上定义 POST 方法。

我希望能够在请求正文中指定多个字段，并且希望生成的文档能够反映出只有 2 个字段是必需的，其他字段是可选的。

我必须做什么/改变才能做到这一点？

我已经尝试过使用“required”关键字进行各种变体（请参见下图），但无法实现该功能，它没有显示在生成的文档中（请参见右下图和我的注释）红色的）。

这是我在编辑器中的 POST 定义：

这是生成的文档预览，我在其中指出了我希望看到更改的内容。

附言。还有一些（较旧的）帖子解决了这个问题，但我真的不认为这是重复的。