标签: openapi

那里肯定有人已经遇到过这种情况......

我创建了一个 WebApi 解决方案，实现了 swagger，完整的文档，整个 9 码！

• 当我运行我的 Web api 解决方案时，请查看 swagger 输出（并且我已经测试了端点，一切正常）
• 我可以看到 swagger 定义：https://localhost:5001/swagger/v1/swagger.json

现在，我想在我的 Web 应用程序上将此 Api 作为连接服务使用。因此，请遵循在线的每个教程：

• 我转到我的网络应用程序
• 右键单击连接服务
• 添加连接服务
• 添加服务引用 > OpenApi > 添加 URL、命名空间和类名

这会在我的解决方案中生成一个部分类（MyTestApiClient）

public parial class MyTestApiClient
{
   // auto generated code
}

下一步，在 Startup.cs 中注入服务

services.AddTransient(x =>
{
   var client = new MyTestApiClient("https://localhost:5001", new HttpClient());
   return client;
});

然后，将类注入到使用它的某个类中，这一切都有效

public class TestService
{
    private readonly MyTestApiClient _client; // this is class, not an interface -> my problem
    public TestService(MyTestApiClient client)
    { …

我正在使用 Swagger 版本 2.1.9 从 Springfox 迁移到 Springdoc。

因此，必须重写注释，并且我找不到旧 Swagger 注释的等效注释。

我有这个 API 控制器：

@GetMapping
@ApiOperation(value = "Load Building")
@ApiResponses(value = {
   @ApiResponse(code = 200, message = "OK", response = Building.class, responseContainer = "Page")
})
public ResponseEntity<Page<Building>> getBuilding(Pageable building) {
   final Page<Building> building = buildingrepo.findAll(page).map(bw -> mapper.map(bd, Building.class));

return ResponseEntity.ok().body(building);

使用新的 Swagger 注释，必须重新编写它，但我不知道如何将“Building.class”放入响应架构中的可分页中。我不能再使用“responseContainer”

@GetMapping
@Operation(summary = "Load Building")
@ApiResponses(value = {
   @ApiResponse(responseCode = "200", 
                description = "OK",
                content = @Content(schema = @Schema(implementation = Building.class))) // <--- Here i need the …

我正在尝试在 Visual Studio 2019..Net 5.0 中生成 OpenApi 服务引用。

右键单击项目>添加>连接服务>+服务引用

我正在使用 NetDocs api“https://api.vault.netvoyage.com/v2/swagger/docs/v2”。

结果：我生成了 c# 客户端代码，但它复制了类型，并出现以下错误。

Severity    Code    Description Project File    Line    Suppression State
Error   CS0102  The type 'v2Client' already contains a definition for '_settings'   OpenAPITest C:\Users\dryfus\source\repos\OpenAPITest\obj\v2Client.cs    4941    Active
Error   CS0579  Duplicate 'System.CodeDom.Compiler.GeneratedCode' attribute OpenAPITest C:\Users\dryfus\source\repos\OpenAPITest\obj\v2Client.cs    4936    Active
Error   CS0102  The type 'v2Client' already contains a definition for '_baseUrl'    OpenAPITest C:\Users\dryfus\source\repos\OpenAPITest\obj\v2Client.cs    4939    Active
Error   CS0102  The type 'v2Client' already contains a definition for '_httpClient' OpenAPITest C:\Users\dryfus\source\repos\OpenAPITest\obj\v2Client.cs    4940    Active

有没有一种方法可以让它与连接器方式一起工作而无需重复？甚至是 cli？关于为什么创建重复项有什么建议吗？

我想为要使用 Swagger 记录的请求参数定义正则表达式。事实上我想定义文件名的格式。在Spring（引导）中使用注释可以吗？
这里：

   @Bean
    default OpenAPI customOpenApi() {

        return new OpenAPI()
            .info(new Info()
                .title("")
                .version("1.0")
                .description(""))
            .components(new Components()
                    .addParameters(
                            "api-version", new io.swagger.v3.oas.models.parameters.Parameter()
                            .name("api-version")
                            .required(Boolean.TRUE)
                            .allowEmptyValue(Boolean.FALSE)
                            .description("")
                            .in("header")
                            .schema(new io.swagger.v3.oas.models.media.Schema<String>().type("string").example("1.0.0"))
                    )
                    .addParameters(
                            "file-name", new io.swagger.v3.oas.models.parameters.Parameter()
                            .name("file-name")
                            .required(Boolean.TRUE)
                            .allowEmptyValue(Boolean.TRUE)
                            .description("Filename of the file to be imported in the following format: " +
                        "<ul>" +
                        " <li><b>yyyyMMdd_DocumentType_senderID_rexeiverID_xxx_version.xml</b></li>" +
                        "</ul>")
                            .in("header")
                            .schema(new io.swagger.v3.oas.models.media.Schema<Integer>().type("string").example("20210228_A14_123456789_987654321_xxx_123.xml"))
                    )
            );
    }

或在这里：

    ResponseEntity<ResponseBody> postData(
        @RequestHeader HttpHeaders headers,
        @RequestAttribute(name = REQUST_ID, required = false) String requestId,
        @Parameter(name = API_VERSION_HEADER_PARAMETER) …

我正在为我的 API 编写 OpenAPI 定义。我正在使用components响应，但当我尝试引用这些组件时，Swagger Editor 显示错误：

responses:
  - $ref: '#/components/responses/401'
  - $ref: '#/components/responses/400'

引用响应组件的正确方法是什么？

我在 Azure 函数应用程序 (v3) 中添加了 OpenApi 支持，.ConfigureOpenApi()使用Program.Main(). 我对特定功能使用函数装饰，但如何控制 ~/api/swagger/ui 上显示的通用 API 名称、版本等？

这是我的Program.Main()代码：

        public static void Main()
        {

            var host = new HostBuilder()
                .ConfigureFunctionsWorkerDefaults(worker => worker.UseNewtonsoftJson())        
                .ConfigureOpenApi()
                .ConfigureServices(services =>
                    {
                        services.AddLogging();
                    }
                )
                .Build();

            host.Run();
        }
    }

目前 OpenAPI 文档如下所示： 是否可以将其分成多个部分？

例如，2 个部分，一个是“books”部分，包含来自“/api/bookcollection/books/”端点的方法，另一个包含“/api/bookcollection/authors/”端点的方法。

我查阅了 FastApi文档，但没有找到任何接近我想要执行的操作的内容。

我在 SpringBoot 项目中使用 OpenApi 3 来生成 Swagger html 页面。

POM.xml 中的依赖项：

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.5.12</version>
    </dependency>

Run Code Online (Sandbox Code Playgroud)

在控制器类中，我在方法上方定义了以下注释。

@Operation(
        summary = "Get a list of letters for a specific user",
        description = "Get a list of letters for a specific user",
        tags = {"letters"}
)
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "success", content = {@Content(
                                                                    mediaType = "application/json",
                                                                    array = @ArraySchema(schema = @Schema(implementation = LetterDTO.class)))}),
        @ApiResponse(responseCode = "400", description = "BAD REQUEST"),
        @ApiResponse(responseCode = "401", description = "UNAUTHORIZED"),
        @ApiResponse(responseCode …

我意识到关于为什么 Java 或其他语言不支持无符号整数有很多类似的问题，但这些都是关于语言设计背后的基本原理和哲学的问题，旨在表达新事物的创造力。

OpenAPI 应该是描述性的。如果 API 想要公开 64 位无符号字，它应该能够做到。OpenAPI 应该有助于代码生成器构建客户端来使用该 API。

好吧，这个论点可以无限地进行，以允许各种奇异的原始类型。这可以被指出为“他们必须在某处划清界限”。

但无符号 32 位和 64 位字是非常常见的原语。为什么他们不受支持？

额外奖励：哪些 REST API 规范格式支持它们？

通过下面的代码，我试图提及替代模式；它们共享相同的接口，作为响应的类型。

启动.cs

services.AddSwaggerGen(c =>
{
    c.UseOneOfForPolymorphism();
});

app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
});

楷模

public interface IOutput
{
    string Discriminator { get; }
}

public class OutputA : IOutput
{
    public string Discriminator => GetType().Name;

    public string PropA { get; set; }
}

public class OutputB : IOutput
{
    public string Discriminator => GetType().Name;

    public string PropB { get; set; }
}

控制器

[HttpGet]
[ProducesResponseType(typeof(IOutput), StatusCodes.Status200OK)]
public IActionResult Get()
{
    return Ok();
}

我期望这两种类型OutputA都会OutputB …