标签: openapi

我想向我的 Node.js API 添加文档，为此我有一个 YAML 文件，我在其中放置我的定义，swagger 文档位于 localhost:5000/api-doc 并且工作正常。

现在我必须添加 Bearer 授权，但 Swagger 具有以下定义：

swagger: "2.0"
info:
    version: 1.0.0
    title: My API documentation
    description: >
        My API documentation

host: localhost:5000
basePath: "/v1"
schemes:
    - http
securityDefinitions:
    Bearer:
        type: apiKey
        description: "Value: Bearer "
        name: Authorization
        in: header
paths:
    /users:
        get:
            responses:
                "200":
                    description: "Will send `Authenticated`"
                "403":
                    description: "You do not have necessary permissions for the resource"

测试请求时（我单击右上角的“授权”按钮并输入我的令牌），出现以下错误：

“错误”：“未找到授权标头。

为什么Authorization请求中不包含标头？

Swashbuckle version="5.6.0" targetFramework="net451" 生成"swagger": "2.0"规范。有没有办法生成 3.0 规范？

在Asp.Net Core中我们可以生成3.0，那么在Asp.Net Framework WebApi中呢？

我的应用程序是 Spring MVC 无法启动。

我正在使用 springdoc-openapi-ui 1.4.4

另外，我将以下导入添加到我的 @configuration 类之一；

    org.springdoc.core.SpringDocConfigProperties.class, org.springdoc.core.SpringDocConfiguration.class, 
    org.springdoc.webmvc.core.SpringDocWebMvcConfiguration.class,
    org.springdoc.webmvc.core.MultipleOpenApiSupportConfiguration.class,
    org.springdoc.core.SwaggerUiConfigProperties.class, org.springdoc.core.SwaggerUiOAuthProperties.class,
    org.springdoc.webmvc.ui.SwaggerConfig.class, org.springdoc.core.CacheOrGroupedOpenApiCondition.class,
    org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration.class })

并按如下方式实现 bean

@Bean
public GroupedOpenApi publicApi() {
    return GroupedOpenApi.builder()
            .group("user")
            .pathsToExclude("/api/v2/**", "/v2/**")
            .pathsToMatch("/api/v1/**", "/v1/**")
            .build();
}
@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("admin")
            .pathsToExclude("/api/v1/**", "/v1/**")
            .pathsToMatch("/api/v2/**", "/v2/**")
            .build();
}

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .components(new Components())
        .info(new Info()
            .title("titleI")
            .version("1.0.0"));
}

但当我尝试时http://localhost:8080/MyApp/v3/api-docs/user

给我 404。

但我得到了列出的所有 APIhttp://localhost:8080/MyApp/v3/api-docs

也进来了http://www.onlykalu.com:81/MyApp/swagger-ui/index.html?configUrl=/MyApp/v3/api-docs/swagger-config

也没有定义下拉。

如果我添加

springdoc.group-configs[0].group=user
springdoc.group-configs[1].group=admin

到 application.properties …

我正在尝试将项目改编为.net5，并希望使用添加 OpenAPI 服务引用的新功能。据我了解，NSwag 将用于生成客户端。我过去已经使用 NSwag 来实现此目的，我可以使用clientBaseInterface选项来指定客户端接口的基本接口，即

interface IClient: **IClientBase** {}
class Client: IClient {}

另请参阅https://github.com/RicoSuter/NSwag/issues/2772。

我尝试对我的 .net5 项目使用以下配置，但不会为生成的类型指定基本接口：

  <ItemGroup>
    <OpenApiReference Include="openapi.json" CodeGenerator="NSwagCSharp" Namespace="MyNamespace">
      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
      <ClassName>MyOpenApiClient</ClassName>
      <OutputPath>MyOpenApiClient.cs</OutputPath>
      <Options>/GenerateClientInterfaces:true /UseBaseUrl:false /ExceptionClass:OpenApiException /ClientBaseInterface:MyBaseInterface</Options>
    </OpenApiReference>
  </ItemGroup>

有谁知道如何在 .net 项目文件中使用此选项？

更新： 由于 NSwag 正在创建部分类和接口，一个简单的解决方法是在部分接口中添加 IClientBase 接口，即

// partial extension
partial interface IClient : **IClientBase** {}

// generated code
partial interface IClient {}
partial class Client: IClient {}

然而，了解我们是否可以直接在 .net 项目文件中管理它仍然很有趣。

我正在寻找一些解决方案，或者可能是一些脚本，可以帮助我通过模式验证替换（$ref）或扩展其在 YML 文件中的定义。（具体请看下面的例子）

**示例：使用 $ref 输入 **

  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pet"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: …

我的nodejs应用程序有一个open-api.yaml文件和express-openapi-validate验证器。我正在执行一个正在运行的 POST 请求，并且 api 验证器不会返回任何错误：

curl --request POST 'http://localhost:33004/my-app/settings' --data-raw '{"serials":["1234","2355"]}' -H 'Content-Type: application/json'

在我的 open-api.yaml 中，我有：

openapi: '3.0.0'
servers:
 - url: 'http://{host}/my-app'
   variables:
     host:
     enum:
       - 'localhost'
       ....
...
paths:
    /settings:
      ...
      post:
        tags:
          - 'settings'
        operationId: 'postSettings'
        requestBody:
          content:
            application/json:
              schema:
                type: object
                properties:
                  serials:
                    type: array
                    items:
                      type: string
...

然后我尝试对我的应用程序进行 docker 化 - 创建一个 docker 容器，并使用 pm2-runtime 在内部运行它。但是，当我在应用程序在其中运行时向 docker 容器发送相同的请求时，我得到error while validating request: request should have required property '.headers'. 我在 open-api.yaml 文件中没有提到属性“.headers”。 …

我有一个 Spring 启动应用程序。我正在尝试从 Swagger 2 切换到 OpenAPI v3。早些时候，我依赖于https://github.com/kongchen/swagger-maven-plugin，它非常棒，用于支持 yaml/ 等工件的编译/构建时生成json。现在，由于 kongchen 存储库中不提供 openAPI v3 支持，我被迫转向https://github.com/springdoc/springdoc-openapi-maven-plugin。但是，这个“springdocs-openapi”插件依赖于要运行的服务器，因为它使用集成阶段。在许多 CI/CD 环境中，在构建阶段让服务器启动并运行实际上是不可行的。是否存在限制，为什么在编译阶段没有可用于构建 openAPI 规范的基于反射的选项？谁能帮我找到替代方案来解决这个问题？

我正在开发一个基于服务的应用程序，我正在为其添加openapi基于注释，例如@RequestBody, @Parameter, @Schema在“@Schema我有一个example字段”中，我可以为其提供格式示例模板String。

我已经提供了，example JSON string但 JSON 内容很大，所以我想将其添加到file我的resources文件夹中。但我目前无法加载它。有人可以让我知道如何添加文件中的示例内容而不是字符串吗？

我尝试查找，发现有一个字段externalValue，但我无法理解如何使其工作。以下是文档的链接。

以下是我的代码，它工作得很好：

@Path("/generate")
@POST
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RequestBody(description = "InputTemplate body",
        content = @Content(schema = @Schema(implementation = InputTemplate.class, example = "{\n" +
                "  \"names\":[\n" +
                "    \"Batman\",\n" +
                "    \"Superman\",\n" +
                "    \"Ironman\"\n" +
                "  ],\n" +
                "  \"jobs\":[\n" +
                "    \"Fighting\",\n" +
                "    \"Fyling\",\n" +
                "    \"Teching\"\n" +
                "  ]\n" +
                "}"))) …

我正在构建一个 FastAPI 应用程序，其中有很多 Pydantic 模型。尽管应用程序运行良好，但正如预期的那样，OpenAPI (Swagger UI) 文档并未在该Schemas部分下显示所有这些模型的架构。

这是pydantic的内容schemas.py

import socket
from datetime import datetime
from enum import Enum
from typing import Any, Dict, List, Optional, Set, Union

from pydantic import BaseModel, Field, validator
from typing_extensions import Literal

ResponseData = Union[List[Any], Dict[str, Any], BaseModel]


# Not visible in Swagger UI
class PageIn(BaseModel):
    page_size: int = Field(default=100, gt=0)
    num_pages: int = Field(default=1, gt=0, exclude=True)
    start_page: int = Field(default=1, gt=0, exclude=True)

# visible under schemas on Swagger UI
class …

我想构建一个 Maven 模块，使用 来openapi-generator-maven-plugin从两个 openapi 3 规范生成服务器代码和客户端代码。我希望服务器代码使用 Spring boot，因此我有以下设置：

<generatorName>spring</generatorName>
<library>spring-boot</library>

这工作正常，我需要io.swagger.core.v3:swagger-annotationsOAS jakarta.validation:jakarta.validation-api3 注释和验证。

但是，对于客户端代码，我想使用WebClientSpring，我能找到的唯一设置是：

<generatorName>java</generatorName>
<library>webclient</library>

客户端代码生成，但问题是，它需要较旧的io.swagger:swagger-annotations和javax.validation:validation-api.

我想避免拥有不同的库集。是否有使用同一组注释和验证库的服务器和客户端代码生成设置？最好同时使用io.swagger.core.v3:swagger-annotations和jakarta.validation:jakarta.validation-api。