标签: openapi

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

 *     @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 规范（特别是使用 Swashbuckle 和 ASP.NET Core）记录现有 API。\n对于许多终结点，API 使用单个查询参数，该参数是一个对象 \ filterxe2\x80\x93 ，其中包含实际的参数 \xe2\x80\x93 是 base64 编码的。

我已经成功添加了Swashbuckle库并且可以生成swagger.json。

然而，生成的规范并未正确描述上述端点。相反，过滤器对象的属性名称被声明为查询参数，因此基于规范的自动生成的客户端不起作用。

该规范仅提及与format字符串和文件相关的 base64，而不是与对象相关的。

\n

1. 是否可以（如果可以，如何）在 OpenAPI 中描述这种类型的端点？

   \n
\n

2. 是否可以（如果可以，如何）使用 Swashbuckle 正确生成此描述？

   \n
\n

回应评论（可能是回答子问题 2) 所必需的）。

API 源中的端点可能类似于：

[HttpGet("")]\npublic async Task<IActionResult> Query([FromQuery] ThingFilter filter)\n{\n    var results = await _dataContext.ThingService.Search(filter);\n    \n    return Ok(results);\n}\n

aThingFilter可能是这样的：

public class ThingFilter\n{\n    public string Freetext { get; set; }\n    public List<PropertyFilter> PropertyFilters { …

我有一个使用 Java 11 的 Spring Boot (2.4.0) REST 服务。端点和对象是使用 openapi-generator-maven-plugin v5.0.1 从 OpenAPI 3.0.3 文件生成的

在 API 中，有一个 GET 请求需要两个查询参数。其中至少必须有一名在场。此示例提到使用 minProperties。尽管我已在 OpenAPI 文件中指定了minProperties，但自动生成的对象不会验证这一点。有办法让它发挥作用吗？

OpenAPI 3.3 代码片段：

parameters:
- in: query
  name: id
  required: true
  style: form
  explode: true
  schema:
    title: EntityId
    type: object
    properties:
      businessId:
        type: string
      nonBusinessId:
        type: string
    minProperties: 1
    additionalProperties: false

openapi-generator-maven-plugin 配置文件：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.0.1</version>
    <executions>
        <execution>
            <id>generate-api</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.build.directory}/swagger/apis/api.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>com.acme.api</apiPackage>
                <modelPackage>com.acme.api.dto</modelPackage>
                <configOptions>
                    <dateLibrary>java8</dateLibrary>
                    <interfaceOnly>true</interfaceOnly>
                    <java8>true</java8>
                    <useBeanValidation>true</useBeanValidation> …

我正在尝试从 OpenAPI json 文件生成 NSwag C# 客户端。

当我这样做时，我确实生成了一个客户端文件，但它无法编译。它在同一个 .cs 文件中创建了 2 个部分类。

现在，如果我将这些类名之一更改为其他名称，该文件现在可以编译：

没有错误 - 编译正常。

所以我的问题是：为什么要这样做？

这是我的 Swagger UI 的图片（这是用 Swashbuckle 生成的，而不是 NSwag）：

所以这意味着我的项目中有 2 个控制器：

• 家庭控制器
• 文件控制器

有什么技巧可以解决这个问题吗？

我使用以下命令行来生成客户端：

dotnet-openapi --updateProject .\MyProject.csproj http://localhost:5100/swagger/v1/swagger.json

据我所知，Dotnet-openapi 正在“幕后”使用 NSwag CSharpClientGenerator。

我很高兴使用任何其他工具来生成 C# 客户端。

我正在 .Net 5.0 Web API 中使用 Swashbuckle (6.1.1)。我仍在学习，但我想实现一个类，其中某些属性仅在使用 a 进行“读取”时有效GET，而其他属性仅在使用 a 进行“写入”时有效POST。根据OpenAPI 规范：

\n

您可以使用 readOnly 和 writeOnly 关键字将特定属性标记为只读或只写。这很有用，例如，当 GET 返回的属性多于 POST \xe2\x80\x93 中使用的属性时，您可以在 GET 和 POST 中使用相同的架构，并将额外的属性标记为只读。readOnly 属性包含在响应中，但不包含在请求中，writeOnly 属性可以在请求中发送，但不包含在响应中。

\n

这正是我想要实现的目标。然而，我正在努力让 Swashbuckle 使用readOnly和writeOnlykeyworks 生成 OpenAPI 规范。

例如：

    public class testDetails\n    {            \n        public string commonProperty { get; set; }           \n        public  string readOnlyProperty { get; set; }\n        public string writeOnlyProperty {  get; set; }\n    }\n\n …

我想使用Arrow类型作为FastAPI响应，因为我已经在SQLAlchemy模型中使用它（感谢sqlalchemy_utils）。

我准备了一个小型的独立示例，其中包含一个最小的 FastAPI 应用程序。我希望这个应用程序product1从数据库返回数据。

不幸的是，下面的代码给出了异常：

Exception has occurred: FastAPIError
Invalid args for response field! Hint: check that <class 'arrow.arrow.Arrow'> is a valid pydantic field type

Exception has occurred: FastAPIError
Invalid args for response field! Hint: check that <class 'arrow.arrow.Arrow'> is a valid pydantic field type

要求.txt：

sqlalchemy==1.4.23
sqlalchemy_utils==0.37.8
arrow==1.1.1
fastapi==0.68.1
uvicorn==0.15.0

这个错误已经在那些 FastAPI 问题中讨论过：

1. https://github.com/tiangolo/fastapi/issues/1186
2. https://github.com/tiangolo/fastapi/issues/2382

一种可能的解决方法是添加此代码（源代码）：

import sqlalchemy
import uvicorn
from arrow import Arrow
from fastapi import …

假设我的 openapi.yml 中有这个定义（这只是一个虚构的示例来描述我遇到的问题）：

components:
  schemas:
    Address:
      type: object
      properties:
        name:
          type: string
        zip:
          type: integer
          format: int64
        town:
          type: string

这将导致生成如下所示的模型代码：

public class Address   {
  @JsonProperty("name")
  private String name = null;

  @JsonProperty("zip")
  private Long zip = null;

  @JsonProperty("town")
  private String town = null;
...

我的问题是，我必须将这个 Pojo 保留在数据库中，并且不存在表Address（让我们假设它被调用Places），并且邮政编码的列被调用zipcode而不是zip.

所以我需要两件事：

• 一种告诉 OpenAPI 有关别名Address=Places和zip=zipcode.
• 一种使此信息更改所创建的代码的方法。例如，对于 Hibernate，这意味着在正确的位置添加@Table(name="Places")和。@Column(name="zipcode")

重要提示：我无法更改 API，预计会坚持使用Address和zip。

这可以做到吗？我检查了规范以及 swagger-codegen …

我想向我的 dto 添加一个描述字段（也是为了满足no_schema_descriptionOpenAPI linting），但找不到这样做的方法。使用哪个装饰器？在定义 dto 时还是在响应中？

更新（澄清）：我希望定义整个架构的描述，而不是单个属性的描述。

我想知道 Swagger 中是否有一个选项可以授权对包含外部文档的 url 的请求。

我有以下配置，我感兴趣的是urls[1]部分

springdoc.swagger-ui.urls[0].url=/v3/api-docs
springdoc.swagger-ui.urls[0].name=default
springdoc.swagger-ui.urls[1].url=https://asdasd.blob.core.windows.net/my-api/docs.spec
springdoc.swagger-ui.urls[1].name=additional

我可以从服务器（直接从机器上curl）访问文档，但是从Swagger（因此浏览器）我不能。我想知道是否有一个选项可以添加例如。Authorization Bearer xxxx对此请求或实际上使服务器发出请求，而不是客户端。

为了澄清 -我想从远程服务器获取带有 OpenAPI 定义的第二个文件，所以我正在谈论这个：

不是Authorize部分

我实施的解决方案：

海伦指出的可行 - 拦截请求并添加标头 - 但不幸的是，在我的情况下，还存在与存储的防火墙设置有关的问题。只有来自服务器的流量，而不是客户端（浏览器）通过，所以我：

1. 将 url 设置为我的域中的某个内容
   springdoc.swagger-ui.urls[1].url=v3/api-docs/additional
2. 为远程主机的 url 指定另一个属性
   mydomain.swagger-ui.additionalDocsUrl=...
3. 实现了一个处理该 url 的自定义控制器 - 它作为服务器而不是客户端从远程获取 json，以便防火墙传递该请求
   

@Hidden
@RestController
@RequestMapping("/v3/api-docs/additional")
@RequiredArgsConstructor
public class AdditionalOpenApiController {

    @Value("${mydomain.swagger-ui.additionalDocsUrl}")
    private String additionalDocsUrl;

    @Cacheable(value = "ADDITIONAL_API_DOCS", unless = "#result != null")
    @GetMapping(produces = "application/json")
    public String getAdditionalDocs() {
        // in my case remote produces application/octet-stream …

我正在尝试使用 PCKE 获取 OAuth 代码流，以便与 .NET 6 中的 Swashbuckle (6.2.3) 和 swagger ui 一起使用。有一些成功发生的事情：

• 在 swagger UI 中，我可以单击“授权”按钮并重定向到 Azure 进行登录。
• 重定向成功返回到 swagger ui，我可以在网络选项卡中看到令牌是通过 swagger ui 从 Azure 检索的。

问题是，当我尝试使用 swagger UI 调用示例天气预报 API 时，授权标头中没有附加任何令牌，并且请求中如下所示：

authorization: Bearer undefined

这是我的代码：

authorization: Bearer undefined

我不确定我错过了什么。有任何想法吗？

更新：我已经能够让它与这样的东西一起工作：

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAdB2C"));

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    
    const string oAuth2 = …