标签: openapi

我正在尝试为现有 API 创建 OpenAPI 3.0 定义。它具有 POST 操作并将标头值作为输入。请求正文为空。Content-Type: application/json然而，后端 API 的编码非常糟糕，即使正文为空，也需要请求标头。

如何在 OpenAPI 3.0 中实现这一目标？看起来Content-Type在 OAS 3.0 中不被接受为有效的标头参数。

我正在使用 Open API 代码生成器 Maven 插件从文件生成 Open API 3.0。我在我的 pom.xml 中使用这个插件：

<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>4.3.0</version>

该插件生成 API 时没有任何问题，但它不使用 Swagger v3 注释，而是使用旧的 Swagger 注释。例如，参数使用 进行注释@ApiParam，而@Parameter应使用io.swagger.v3.oas.annotations包中的注释：

default ResponseEntity<Fault> getFault(@ApiParam(value = "",required=true) @PathVariable("jobId") String jobId) {

因此，最新的 Swagger UI 无法正确显示文档。当我使用 swagger.v3 注释创建端点时，Swagger UI 可以正常工作。

根据官方网站https://openapi-generator.tech/docs/plugins/，我应该包含这个依赖项：

<dependency>
    <groupId>io.swagger.parser.v3</groupId>
    <artifactId>swagger-parser</artifactId>
</dependency>

但即使有这种依赖性，插件仍然会生成带有旧注释的源。

如何强制 Open API 代码生成器使用 Swagger v3 注释？

我正在使用在线Swagger编辑器为我的API创建Swagger规范.

我的API有一个GET请求端点,我使用以下YAML代码来描述输入参数:

paths:
  /fooBar:
    get:
      tags:
        - foobar
      summary: ''
      description: ''
      operationId: foobar
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - application/json
      parameters:
        - name: address
          in: query
          description: Address to be foobared
          required: true
          type: string
          example: 123, FakeStreet
        - name: city
          in: query
          description: City of the Address
          required: true
          type: string
          example: New York

如果我放入example标签,我会收到错误消息:

不是<#/ definitions/parameter>,<#/ definitions/jsonReference>中的一个

如何在Swagger中编写GET参数时设置示例？

我SecurityScheme对 java SpringBoot RESTful 应用程序使用 springdoc-openapi有以下定义：

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components().addSecuritySchemes("bearer-jwt",
                 new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
                .in(SecurityScheme.In.HEADER).name("Authorization")))
                .info(new Info().title("App API").version("snapshot"));
    }

是否可以将其全局应用于所有路径，而不必在代码中的任何地方添加@SecurityRequirement注释@Operation？

如果是，如何向不安全的路径添加排除项？

是否有任何工具/库可以将 OpenAPI 2.0 定义转换为 OpenAPI 3.0，而不是每行一个？

我正在寻找一种方法来告诉 swagger 某个 API 响应代码没有响应正文。例如，获取响应可以返回 200 代码以及实际对象作为响应，如果与传递的 ID 关联的对象不存在，则返回 404：

@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Object found"),
    @ApiResponse(responseCode = "404", description = "Invalid object ID", content = @Content)
})

这是我能想到的最接近的东西，但它并不完美，我仍然在 404 响应的描述下得到一个烦人的“媒体类型”。谢谢！

我正在努力寻找一种解决方案，如何将多个 OpenApi v3 组件定义合并到一个文件中。

让我们想象一个情况：

1. 您决定将 OpenApi 拆分为不同文件夹中的多个文件。（见下图）
2. 现在您需要将所有的 Components.v1.yaml 合并到一个架构中（我将其命名为blueprint.v1.yaml）。通常，我用来swagger-cli合并所有$ref依赖项，但现在不是这样，因为我无法引用整个组件/模式对象列表
3. 并使用它通过工具构建一个填充了所有字段的 OpenApi 文件：信息、组件、路径等swagger-cli bundle。

所以，问题是 - 如何在我的blueprint.v1.yaml文件中重用已定义的组件块（名为 Components.v1.yaml 的文件）？

PS 每个components.v1.yaml看起来都是这样的：

例如，location-create-single.v1.yaml路径定义如下图所示。值得一提的是，所有这些都是$ref指components.v1.yaml文件。

对于我记录的旧 API 以便成功进行身份验证，我需要提供以下标头：

X-Access-Token: {token}
Accept: application/json; version=public/v2

对于令牌部分，我需要通过以下方式记录它：

X-Access-Token: {token}
Accept: application/json; version=public/v2

但是我如何记录这一点以进行身份​​验证，我需要提供Accept: application/json; version=public/v2. 标Accept头必须包含application/json; version=public/v2任何其他返回406 Not Acceptable标头。

Accept另外，具有值的标头application/json; version=public/v2应该在我的请求中。响应标头始终为application/json.

你知道我如何记录这一点吗？

问题

我目前有名为 jwt 的 JWT 依赖项，它确保它在到达端点之前通过 JWT 身份验证阶段，如下所示：

sample_endpoint.py:

from fastapi import APIRouter, Depends, Request
from JWTBearer import JWTBearer
from jwt import jwks

router = APIRouter()

jwt = JWTBearer(jwks)

@router.get("/test_jwt", dependencies=[Depends(jwt)])
async def test_endpoint(request: Request):
    return True

以下是使用 JWT 对用户进行身份验证的 JWT 依赖项（来源：https ://medium.com/datadriveninvestor/jwt-authentication-with-fastapi-and-aws-cognito-1333f7f2729e ）：

JWTBearer.py

from typing import Dict, Optional, List

from fastapi import HTTPException
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from jose import jwt, jwk, JWTError
from jose.utils import base64url_decode
from pydantic import BaseModel
from starlette.requests import Request …

我正在开发一个使用 NestJS 框架的 Node.js 服务器。我想使用NestJS 的 swagger 集成为应用程序自动构建 API 文档。

为我的控制器方法正确生成了用于@Body()控制器数据交换的方法的文档。对于使用该方法的控制器方法，它无法正常工作@Param()。无法生成正确文档的示例控制器：

  @Get('/:identifier')
  @RouteLogger()
  @ApiParam({name: 'identifier', required: true, description: 'either an integer for the project id or a string for the project name', schema: { oneOf: [{type: 'string'}, {type: 'integer'}]}})
  async getProject(
    @Param('identifier')
    identifier: string | number,
    @Res() res: Response
  ) { }

这会在 swagger UI 中生成以下内容：

您可以看到 swagger UI 中的端点无法显示具有任何参数的端点。使用 s 为 NestJS 控制器编写 GET 端点@Param以便 swagger 正确生成文档的正确方法是什么？