标签: openapi

我正在使用 OpenAPI Generator 创建客户端，但是当我尝试发出 POST 请求时，LocalDateTime 会被序列化为整数数组，看起来像

{
  "startDate": [ 2019, 11, 13, 0, 0 ],
  "endDate": [ 2020, 12, 31, 0, 0 ]
}

我正在等待这个结果，像 ISO 字符串一样解析

{
  "startDate": "2019-11-13T00:00",
  "endDate": "2020-12-31T00:00"
}

我的gradle配置是这样的：

dependencies {
  compile 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310:2.10.3'
  classpath 'org.openapitools:openapi-generator-gradle-plugin:4.2.3'
}

task generateClientDS(type: org.openapitools.generator.gradle.plugin.tasks.GenerateTask) {
  inputSpec = "$rootDir/specifications/client-ds.yaml".toString()
  outputDir = "$rootDir".toString()
  generatorName = 'java'
  library = 'resttemplate'
  apiPackage = 'com.example.gen.clients.clientds.api'
  modelPackage = 'com.example.gen.clients.clientds.dto'
  modelNameSuffix = 'DTO'
  configOptions = [
          hideGenerationTimestamp: 'true',
          dateLibrary: 'java8'
  ]
  typeMappings = [
          OffsetDateTime: 'java.time.LocalDateTime' …

我有一个API，其curl请求如下：

curl --request POST \
  --url 'http://some.url/api/Resource/findByIds' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'data[ids][]=100025' \
  --data 'data[ids][]=100028'

如何在 OpenAPI (Swagger) 请求定义和示例（版本 3）中表示这一点？

这是我到目前为止所拥有的，但我似乎无法让示例正确显示。

    api/Resource/findByIds:
      post:
        summary: Find resource by IDs
        requestBody:
          content:
            application/x-www-form-urlencoded:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      ids:
                        type: array
                        description: IDs of resources to fetch
                        items:
                          type: integer
                encoding:
                  data:
                    style: deepObject
                    explode: true
              example:
                data:
                  ids: [2334, 234, 20043]

因此，我们使用 FastAPI 构建了一个 API，对于 API 的文档，我们首先使用 markdown 并在初始化 FastAPI 对象时传递它，如下所示

main = FastAPI(
    root_path="/public",
    title="API",
    description="""{}""".format(open("public/app/description.md").read()),
)

在我们的description.md文件中，我们使用了markdowns代码块功能来突出显示语法。我们使用的语法是使用反引号和其旁边的编程语言名称，以便它像任何文本编辑器一样突出显示关键字。对于前：

现在，一旦我们运行应用程序并导航到http://localhost/public/docs， FastAPI 就会去掉所有样式并将其设置为纯文本，但我们希望它的显示方式就像上图所示。这是去掉造型后的样子。

我们还尝试使用 HTML/CSS，但 FastAPI 也去掉了样式并将 HTML 呈现为纯文本。有人可以指导我们实现 FastAPI 文档的语法突出显示，以便当我们转到/docs时我们的代码块语法突出显示保持不变任何帮助或线索表示赞赏

我有 swagger 设置，以便它在项目启动时使用 NSwag 基于我的 WebApi 中的控制器生成开放的 Api 规范和 Swagger Ui。我想增强 swagger Ui 以包括

• 每个端点的摘要/描述
• 需要参数输入的端点的示例参数输入
• POST 调用的请求正文示例
• 一个示例访问令牌，只能在 swagger 文档中使用，以轻松进行身份验证并能够尝试一切（有点像此示例https://petstore.swagger.io/）

我是 NSwag 的新手，不确定如何将这些增强功能添加到我的代码中，例如在哪里添加它们，我需要使用什么（控制器上的注释？XML 注释？另一种方式？）我尝试过编辑“ Swagger Editor'，但不知道这是如何实现的，因为它会在每次应用程序启动时重新生成。

我已阅读 NSwag 文档，但这似乎都是关于添加我已经配置的 ASP.NET Core 中间件。

编辑： 我现在在页面顶部有一个描述，并且已经能够在 XML 注释中添加带有备注标记的示例 -有没有比使用 XML 注释更优雅的方法来执行此操作？

我有一个实体（图像），它具有如下计算属性（图像路径）：

@Entity()
export class Image extends BaseEntity {
  @PrimaryGeneratedColumn()
  @IsInt()
  id: number

  @Column({ type: 'varchar', length: 255, unique: true })
  @IsString()
  @IsNotEmpty()
  uid: string

  protected mainPath: string

  @AfterLoad()
  @AfterInsert()
  @AfterUpdate()
  generateMainPath(): void {
    this.mainPath = Math.floor(this.id / 10000) + '/' + Math.floor(this.id / 100) + '/' + this.uid
  }
}

我使用mainPath在后端文件系统中存储图像，并将其发送到前端构建img src路径。mainPath成功生成并发送给客户端。

问题在于前端使用 swagger (nswag openapi2tsclient) 生成的基于 openApi 模式构建的打字稿文件，由 Nest.JS 生成。生成的文件中没有接口mainPath属性。IImage是否可以以某种方式声明它，以便在客户端上定义它并填充 ajax 响应提供的值？

PS1。尝试装饰mainPath-@ApiProperty({ type: String })它没有帮助。

PS2。尝试使用@Column({ type: …

我已经定义了模型 A，它有两个字段，field1这是必需的。

A:
 type: object
 required:
  - field1
 properties:
  field1:
    type: string
  field2:
    type: string

我想创建一个新的模式 B，它具有与 A 相同的字段，但这两个字段都是必需的。

我可以这样写吗？

B:
  allOf:
   - $ref: '#/components/schemas/A'
   - type: object
     required:
     - field2

仅当我通过 ARM 模板部署时，当我从门户尝试成功时，我才会遇到此问题。我认为问题可能出在我使用的版本上，所以我更改了模板中的最后 3 个版本（ https://learn.microsoft.com/en-us/azure/templates/microsoft.apimanagement/service/apis ），还是同样的问题。有人可以指出我这里出了什么问题吗？我添加了最小复制。

昂首阔步：

{
  "openapi": "3.0.1",
  "info": {
    "title": "Test",
    "description": "Test",
    "version": "1.0"
  },
  "paths": {
    "/api/v1/test": {
      "get": {
        "tags": [
          "Test"
        ],
        "summary": "Test",
        "parameters": [
          {
            "name": "TestName",
            "in": "query",
            "schema": {
              "minLength": 3,
              "type": "string",
              "nullable": true
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Server Error",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": …

许多 API/微服务提供对关键资源（包括 Kafka 主题）的访问。API/微服务消息使用定义 API/微服务合约的 OpenAPI 规范进行验证。一旦微服务验证了消息，它就会发布到 Kafka 主题，此时该消息将根据 Kafka 的架构注册表（再次）进行验证。

问题在于，有两个消息定义可供验证消息（OpenAPI 规范和 Kafka 的架构注册表），并且确保两个消息定义同步是一个挑战。

考虑到这一点，我有几个问题：

• 有没有办法将 OpenAPI 规范转换为 Kafka 架构注册表格式（反之亦然）？
• 有没有办法让 Kafka 根据 OpenAPI 规范而不是注册表进行验证（可能不是一个很好的解决方案，因为应该使用本机 Kafka 功能）？
• 有没有办法允许 API/微服务根据 Kafka 模式而不是 OpenAPI 规范验证其消息（同样，这可能不是一个好方法，因为 OpenAPI 规范是定义 API 消息的标准方法）？

最后，上面哪一个最有道理。还有其他更好的选择吗？

我最近从 Springfox 转换为 Springdoc-openapi，以便为 Spring Boot Rest API 服务生成 OpenAPI。

一切都很完美，直到我添加了安全方案。一旦我这样做了，我的方案就不再出现，并且 SwaggerUI 页面上出现错误：

Could not resolve reference: Could not resolve pointer: /components/schemas/Ping does not exist in document

我正在以编程方式设置我的配置，并且有 2 个组。

我正在使用 Spring Boot v2.4.0 和 springdoc-openapi-ui v1.5.1

我的 pom.xml 的片段：

        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.5.1</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-hateoas</artifactId>
            <version>1.5.1</version>
        </dependency>
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-security</artifactId>
            <version>1.5.1</version>
        </dependency>

配置片段：

    @Bean
public GroupedOpenApi apiV1() {
    String[] paths = {"/v1/**"};
    String[] packagesToScan = {"com.test.controller"};
    return GroupedOpenApi.builder()
            .group("v1")
            .packagesToScan(packagesToScan)
            .pathsToMatch(paths)
            .addOpenApiCustomiser(buildV1OpenAPI())
            .build();
}

@Bean
public GroupedOpenApi …

我使用 openApi-generator-maven 插件版本 4.2.3 成功生成了 Rest Api 控制器和模型。在 yaml 合约中，我们引用包含共享模型的外部 YAML 文件：

schema:
  $ref : 'mycontract.yaml#/components/schemas/PrjExceptionHandler'

这个共享的yaml位于特定的包下。有没有办法在生成过程中忽略 yaml 文件（此 yaml 中定义的模型）？实际上，我正在使用 .openapi-generator-ignore 文件来一一忽略模型，例如：

**/PrjExceptionHandler*

我正在寻找一个全局解决方案，在该解决方案中，我可以忽略给定 Yaml 文件或要忽略的包的所有模型，此外，通过执行实际的解决方案，我在生成过程中遇到编译错误，其中对象抱怨PrjExceptionHandler不会被忽略定义的。

感谢您的支持。