标签: openapi

当库尚未准备好供打算使用 API 的其他微服务使用时，如何在 OpenAPI 3.x 中将 API 标记为未使用

注意：目前，我们构建了很多 API，它们处于不同的开发阶段。有没有办法对此进行注释，以便其他开发人员知道有一些 API 仍在进行中

我有这个 OpenAPI 架构：

components:
  schemas:
    User:
      type: object
      required:
        - username
        - email
        - description
        - profile_icon
      properties:
        username
          type: string
        email
          type: string
          format: email
        description
          type: string
        profile_icon
          type: string

所有属性都是必需的。这是为了PUT /user/profile.

我会将其更改为PATCH /user/profile. 用户仅发送他们请求更改的参数。系统验证至少需要一个参数。

我如何描述 [用户名、电子邮件、描述、个人资料图标] 之一是必需的？

可接受的示例请求：

{
  "username": "Will Smith"
}

{
  "email": "test@example.com",
  "profile_icon": "aaaaa.png"
}

不可接受的示例（错误）：

{}

注释anyOf器很接近，但它似乎仅适用于$ref模式，而不适用于属性。

https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/

我将 OpenAPI 与我的项目集成，当我访问 url: 时http://127.0.0.1:11014/swagger-ui/index.html，显示如下错误：

Unable to render this definition
The provided definition does not specify a valid version field.

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

 

这是 OpenAPI 配置：

package misc.config.openapi;

import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * https://springdoc.org/
 * https://github.com/springdoc/springdoc-openapi
 */
@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi …

我有一个用例，由于与 Azure 的兼容性问题，我需要将 OpenAPI 从 3.1 隐藏到 3.0。有人研究过这个用例吗？我们将感谢您的帮助

我有一个 API，我希望 swashbuckle 为我自动生成所有 swagger 文档。

我有一个端点，它返回一个带有字典属性的类，但 swagger 生成的示例包含“additionalProp1、additionalProp2”等而不是示例值。有没有办法改为使用SimpleClass类中指定的示例值？

带有 swagger 示例的类（不起作用）。

public class SimpleClass
{
    /// <example>"{"age":31,"height":234}"</example>
    public Dictionary<string, int> DictionaryProperty { get; set; }

    /// <example>The cow jumped over the moon</example>
    public string someProperty { get; set; }
}

控制器

    [HttpGet]
    [Route("/testexample")]
    [ProducesResponseType(typeof(SimpleClass), StatusCodes.Status200OK)]
    public async Task<IActionResult> TestExample()
    {
        return Ok();
    }

招摇的结果：

我使用 Visual Studio Add-Service-Reference 添加使用 OpenAPI 规范的服务。

我输入了 swagger URL 并生成了代码。

.csproj 表示该服务已配置。

但是，当我尝试构建时出现错误。

该向导包含此链接

该服务是使用 AutoRest 生成的。我使用的是VS2022 17.2.5

完整的错误是

错误 MSB3073 命令“”C:\Users\kirst.nuget\packages\nswag.msbuild\13.0.5\build../tools/Win/NSwag.exe” openapi2csclient /className:myapicls /namespace:myapi /input:D :\dev\MyApi\UnitTestProject1\OpenAPIs\index.html /output:obj\indexClient.cs " 退出，代码为 -1。UnitTestProject1 C:\Users\kirst.nuget\packages\nswag.apidescription.client\13.0.5\build\NSwag.ApiDescription.Client.targets 28

我正在努力解决返回 HashMap<String, List> 的 API 的 API 规范。API 本身完全按照我想要的方式工作，但我希望 OpenAPI 正确指定返回类型。我一直在谷歌搜索并找到 SchemaType.ARRAY，这使它更好，但现在当我在 Swagger 中查看时，它被指定为一个数组，它更接近我想要的 HashMap，而不是我更改 SchemaType 之前的单个对象。

'''

@GET
@Path("/")
@Produces({MediaType.APPLICATION_JSON})
@Consumes({MediaType.APPLICATION_JSON})
@Operation(
        summary = "All grunddata forapplikationen")
@APIResponse(            responseCode="200",
        description="All grunddata in the system",
        content= @Content(schema = @Schema(type = SchemaType.ARRAY, implementation = Grunddata.class))
)

'''

我在搜索时发现的一个有希望的解决方案是创建一个扩展 HashMap<String, List> 的 clss 并使用它来实现，但这只会导致 API 似乎只重新运行一个简单的 String。

我想根据 Openapi 规范 3.0 yml 定义生成模型。在我的规范中，我有一个定义，用于allOf包含其他组件的字段。使用 生成模型时openapi-generator-maven-plugin。我看到以下警告allOf with multiple schemas defined. Using only the first one。

结果是仅allOf包含第一个定义的属性。虽然我希望所有字段都包含在内。https://editor.swagger.io/生成正确的架构。

为什么不是所有属性都定义在allOfinclude 中？

架构定义：

Dto:
  title: Dto
  type: object
  properties:
    created_by:
      type: string
      format: date-time

Foo:
  title: Foo
  type: object
  allOf:
    - $ref: '#/Dto'
  properties:
    fooProperty:
      type: string

Bar:
  title: Bar
  type: object
  allOf:
    - $ref: '#/Foo'
  properties:
    barProperty:
      type: string

maven插件配置：

        <plugin>
            <groupId>org.openapitools</groupId>
            <artifactId>openapi-generator-maven-plugin</artifactId>
            <version>6.1.0</version>
            <executions>
                <execution>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                    <configuration> …

在使用 Swagger 3 OpenAPI 的 Spring Boot 项目中。

有一个文件POST为 的方法。MultipartRequestPart

理想情况下，swagger-ui它应该要求文件上传，但仅将文件显示为String.

请帮助我上传文件而String不是swagger-ui.

我的RestController：

@RestController
public class HelloController {
    @RequestMapping(method = RequestMethod.GET, value = "/api")
    public String sayHello() {
        return "Swagger Hello World";
    }
    @RequestMapping(method = RequestMethod.POST, value = "/fileUpload")
    public String fileUpload(
            @RequestPart(value = "file", required = false ) MultipartFile file,
            @RequestPart(value = "userName", required = false ) String userName
    ) {
        return "added successfully";
    } …

例如，我不想在 FastAPI Swagger 文档中公开字符串的正确正则表达式。如何实现这一目标？

招摇验证错误：

我实际上是通过以下方式实现的：

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return PlainTextResponse(
        str("the string does not match the correct regex"), status_code=422
    )

但它仅在我从 Postman 调用端点时才起作用，但在 Swagger 中，FastAPI 似乎甚至在到达端点之前就抛出验证错误。

我尝试了很多事情，但似乎没有任何效果。