标签: openapi

如何将数组指定为参数？例如,可以为/ people发布字符串username,firstname和lastname,以及数组myArray.

paths:
  /persons:
    post:
      parameters:
        - name: person_what_is_the_purpose_of_this
          in: body
          description: The person to create.
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName:
                type: string
              username:
                type: string
              myArray:
                type: array
                  items:
                    properties:
                      myArrayElement:
                        type: string
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

我正在将Java端点框架(2.0.1)用于Java作为我最后一年项目的一部分,到目前为止它已经相对成功.部署到我的appspot.com域时没有任何问题,但是,我在本地部署时遇到了一些问题.

(以下代码块中对my-project-id的任何引用都是我实际的Google云项目ID的别名)

我有一个带注释的@API类的有效openapi描述符(openapi.json),我使用"gcloud service-management deploy openapi.json"将其部署到云端点.该命令成功返回:

Service Configuration [2017-02-23r0] uploaded for service [api.endpoints.<my-project-id>.cloud.goog]

然后我将返回的config_id映射到app.yaml中正确的endpoints_api_service

endpoints_api_service:
  name: api.endpoints.<my-project-id>.cloud.goog
  config_id: 2017-02-23r0

该服务由gcloud cli工具使用"gcloud service-management list"列出

    NAME                                                           TITLE
    storage-component.googleapis.com                 Google Cloud Storage
    api.endpoints.<my-project-id>.cloud.goog         api.endpoints.<my-project-id>.cloud.goog
    etc...

和"gcloud service-management configs list --service api.endpoints.my-project-id.cloud.goog"

CONFIG_ID        SERVICE_NAME
2017-02-23r0     api.endpoints.<my-project-id>.cloud.goog
... other version configs

并且可以在我的appspot.com域上访问(我可以调用端点并收到正确的响应)

我正在尝试使用java的maven appengine插件(mvn appengine:devserver)在localhost上部署我的项目,但是在jetty启动时我遇到了以下异常:

 WARNING: Failed startup of context com.google.appengine.tools.development.DevAppEngineWebAppContext...

com.google.api.config.ServiceConfigException: Failed to fetch default config version for service 'api.endpoints.<my-project-id>.cloud.goog'. No versions exist!
at com.google.api.config.ServiceConfigSupplier.fetchLatestServiceVersion(ServiceConfigSupplier.java:155)
....

部署然后陷入无休止的循环,尝试启动jetty,并被该错误消息,并重新启动等.任何尝试访问localhost:8080导致"503:服务未找到"错误

我假设我的应用程序的本地部署能够访问使用"gcloud service-management deploy"部署的服务配置,就像appspot.com部署一样,但事实并非如此吗？查看ServiceConfigSupplier.getchLatestServiceVersion()的源代码我收集了serviceManagement.services().configs().list(my-service-name).execute().getServiceConfigs()返回一个空列表,但为什么这只是在当地发生？

额外的信息

我的ENDPOINTS_SERVICE_NAME环境变量与'api.endpoints.my-project-id.cloud.goog'匹配

我注意到几天前com.google.api.config有一个更新(1.0.2),它依赖于旧版本的com.google.api.services.servicemanagement(取决于v1-rev14) -1.22.0,最新版本是v1-rev340-1.22.0)我怀疑这是问题,但我想我会提到它,因为它包含与异常相关的类(ServiceManfigSupplier使用ServiceManagement,它正在抛出例外).他们在寻找服务配置的地方可能存在不一致之处？ …

我正在尝试使用 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> …

我正在 .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 = …