标签: openapi

我有一个描述从 REST 服务获取的数据的架构。我无法改变这个计划。date-time架构中有两个具有不同格式的类型字段：

"date1": {
    "type": "string",
    "description": "Date 1",
    "format": "date-time"
},
"date2": {
    "type": "string",
    "description": "Date 2",
    "format": "date-time"
}

{
    "date1": "2021-07-29T03:00:00",
    "date2": "2021-04-22T08:25:30.264Z"
}

date-time默认情况下，打开的 api-generator-maven-plugin 会为类型字段创建 OffsetDateTime 类型：

    @JsonProperty("date1")
    private OffsetDateTime date1;

    @JsonProperty("date2")
    private OffsetDateTime date2;

typeMappings我可以将importMappingsOffsetDateTime 替换为 LocalDateTime：

<typeMappings>
    <typeMapping>OffsetDateTime=LocalDateTime</typeMapping>
</typeMappings>
<importMappings>
    <importMapping>java.time.OffsetDateTime=java.time.LocalDateTime</importMapping>
</importMappings>

但这种替换将发生在所有字段上：

    @JsonProperty("date1")
    private LocalDateTime date1;

    @JsonProperty("date2")
    private LocalDateTime date2;

有没有办法仅用 LocalDateTime 替换 OffsetDateTime date1？

这就是我想在生成的类中看到的内容：

    @JsonProperty("date1")
    private LocalDateTime date1;

    @JsonProperty("date2")
    private OffsetDateTime …

我试图在我的 swagger 部分description的字段中包含一个图像info，该图像通过 Swagger-UI 显示。到目前为止我已经尝试过 GFM：

...
  "info": {
    "description": "![alt text][/static/img/image.png]"
  }
...

和普通的旧 HTML：

...
  "info": {
    "description": "<img alt=\"alt text\" src=\"/static/img/image.png\">"
  }
...

但这两者都只是按照给定的方式呈现字符串，而不显示图像。

有没有办法做到这一点？

我们正在为当前的 API 制定开放 API 规范。我们希望将生成的文件与 Postman 集成，以生成集合并能够轻松发出请求，而无需在进行新更改时更新集合。

现在，我正在使用以下内容：

openapi: 3.0.0
info:
  version: '1.0.0'
  title: 'Objects API'
servers:
  - url: '{{HOST}}/api/3/users/{{USER_ID}}'

如果我使用它，那么生成的集合看起来像这样：

所以它可以工作，但问题是，如果我们现在将 OpenAPI 文件与 swagger 集成，所有内容{{...}}都会出现在文档中。

我看到邮递员在集合上生成了一些变量，例如baseUrl：

虽然我真的不知道如何在自动生成的请求中使用该变量（也就是说，请求是使用该变量生成的）。

有什么想法/技巧可以解决这个问题并使我们的收藏品尽可能被他们使用吗？理想情况下，用例是在 Postman 上导入 OpenAPI 文件并开始发出有效请求，替换尽可能少的值。

我正在我的应用程序中构建一个新端点，用作express-openapi-validator验证器中间件。

/* index.ts */

import * as OpenApiValidator from 'express-openapi-validator';

const whitelistedPaths = [/* regex tested paths */];

app.use(
    OpenApiValidator.middleware({
      apiSpec: './schema/api.json',
      validateResponses: true,
      ignorePaths: whitelistedPaths,
      validateSecurity: true,
    }),
  );

/* ... */

app.post(
  '/users/:email/validateToken',
  bodyParser.json(),
  (req) => validateToken(req.params.email, req.body.resetToken),
);

在我的配置 ( api.json) 文件中，我将端点的架构定义为：

    "/users/{email}/validateToken": {
      "post": {
        "tags": ["users"],
        "summary": "Validate user token",
        "operationId": "validateToken",
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        },
        "parameters": [
          {
            "name": …

我正在从 Springfox 3.0 切换到 OpenAPI 3.0 + Springdoc-openapi。
在 Springfox 中，标签顺序是按字母顺序排列的，但在 Springdoc 的 Swagger UI 中，顺序似乎是随机的。

如何控制 UI 上的标签顺序？我更喜欢自己选择的顺序，但也可以按标签名称的字母顺序排序。

@Tag(name = MY_CONTROLLER_TAG_NAME, description = MY_CONTROLLER_TAG_DESC)
public class MyController {

所需订单：

• 分页端点
• 用户访问
• 标记
• 标记 - 管理员
• 用户管理
• 用户管理 - 管理员

实际订单：

• 用户访问
• 标记
• 分页端点
• 标记 - 管理员
• 用户管理 - 管理员
• 用户管理

POM 依赖关系：

        <springdoc-openapi.version>1.6.4</springdoc-openapi.version>
...
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>${springdoc-openapi.version}</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-security</artifactId>
            <version>${springdoc-openapi.version}</version>
        </dependency>

应用程序.yml：

springdoc:
  show-actuator: ${SWAGGER_ENABLED:true}
  swagger-ui:
    doc-expansion: none
  api-docs:
    enabled: ${SWAGGER_ENABLED:true}
  model-converters:
    pageable-converter:
      enabled: true

有没有办法以编程方式将构建版本从 Spring Boot 应用程序的 POM 设置为 springdoc-openapi-maven-plugin 生成的 OpenApi YAML？

我怎样才能实现它？

目前我已经通过这种方式集成了 springdoc-openapi-maven-plugin ：

    <plugin>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-maven-plugin</artifactId>
        <version>1.1</version>
        <executions>
            <execution>
                <id>integration-test</id>
                <goals>
                    <goal>generate</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <apiDocsUrl>http://localhost:9090/v3/api-docs.yaml</apiDocsUrl>
            <outputFileName>my_open_api_specification.yml</outputFileName>
            <outputDir>${project.build.directory}/my_open_api_specification/</outputDir>
            <skip>false</skip>
        </configuration>
    </plugin>

我有一个使用 OpenApi 注释来注释方法的接口：

@Tag(name = "API Operationen")
@RequestMapping
public interface RestApi {
...

    @Bean
    default OpenAPI myOpenApi() {
    
        return new OpenAPI()
            .info(new Info()
                .title("The title")
                .version("1.0")           <-- I want to dynamically set this version with the value coming from  BuildProperties (POM version).
                .description("The description"));
    }
}

我使用 …

我正在使用 Spring Boot，并且有一个定义一些端点的 Yaml 文件。我需要为其中一个端点设置别名以拥有不同的端点，但功能完全相同。

举个例子，如果我有一个规范如下：

openapi: '3.0.1'

servers:
  - url: 'http://localhost:8080/api

paths:
  /v3/users
    .... (remainder of endpoint spec)

根据我所读到的内容，我想补充的是：

  /globalusers/v3/users
    $ref: '#/paths/~1v3~1users

当我这样做时，生成的 Spring API 不包含新的 RequestMapping。我尝试复制整个/v3/users定义并将其也放入其中，但没有任何变化。

要么我遗漏了一些东西，要么误解了我读到的内容。感谢所有帮助！

谢谢。

阅读 Stackoverflow 上的这两篇文章后： How to Solved ErrorException : required @OA\PathItem() not find Can't generated API Documentation in l5-swagger

Required @OA\PathItem() not found运行 php artisan l5-swagger:generate 后仍然出现错误。

这是我的 Controller.php 部分：

/**
 * @OA\Info(
 *     title="My First API Documentation",
 *     version="0.1",
 *      @OA\Contact(
 *          email="info@yeagger.com"
 *      ),
 * ),
 *  @OA\Server(
 *      description="Learning env",
 *      url="https://foo.localhost:8000/api/"
 *  ),
 */
class Controller extends BaseController
{

这是我的 ProfileController 部分：

   /**
     * @OA\Get(
     *      path="/profiles",
     *      @OA\Response(
     *          response=200,
     *          description="Successful operation",
     *      ), …

我正在 VSCode 中使用 OpenAPI 3 编写一个 API 文档，扩展名为OpenAPI (Swagger) Editor v4.9.1。直到今天它都运行得很好 - 突然我的文档充满了所有模式声明中“属性”的错误。错误如下：

Missing property "$ref". yaml-schema: Validation schema for OpenAPI Specification 3.0.X.

显然，这个错误根本没有意义，因为根据 OpenAPI 规范，$ref 在任何地方都不是必填字段。
此外，我仍然可以使用 swagger 的默认渲染器预览该文档，或者使用其 CodeGen 工具链生成代码，这表明该文档没有实际错误。
那么发生了什么事？是 OpenAPI 语言服务器中的错误吗？

使用 ORM，我想要执行一个 POST 请求，让某些字段具有null值，该值将在数据库中转换为那里指定的默认值。

问题是 OpenAPI (Swagger) docs忽略了默认值None，并且默认情况下仍然提示 a UUID。

from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional
from uuid import UUID
import uvicorn


class Table(BaseModel):
    # ID: Optional[UUID]      # the docs show a example UUID, ok
    ID: Optional[UUID] = None # the docs still shows a uuid, when it should show a null or valid None value.

app = FastAPI()  
    
@app.post("/table/", response_model=Table)
def create_table(table: Table):
    # here we call …