我正在Swagger编辑器中编写YAML文件.

我的一个类型定义包含一个包含与父类型相同类型的子元素的数组.就是这样的:

definitions:
  TreeNode:
    type: object
    properties:
      name:
        type: string
        description: The name of the tree node.
      children:
        type: array
        items:
          $ref: '#/definitions/TreeNode'

但是,Swagger没有在"children"数组中获取递归引用,该数组简单地显示为"未定义"元素的数组.

有没有人知道如何做到这一点？`

我有一个现有的Spring REST API，我想为其生成OpenAPI 3.0 YAML文件，而不是Swagger 2.0 JSON / YAML？

从现在开始，SpringFox不支持YAML生成。它使用Swagger 2.0（遵循OPEN API 3.0规范）生成JSON。

此外，还有https://github.com/openapi-tools/swagger-maven-plugin，但它似乎不支持Spring Rest。

我尝试了Kongchen spring-maven-plugin，它能够生成YAML文件，但是具有Swagger 2.0定义，而不是像OPEN API 3.0：

swagger: "2.0"
info:
  description: "Test rest project"
  version: "1.0"
  title: "Some desc"
  termsOfService: "http://swagger.io/terms/"
  contact:
    name: "Rest Support"
    url: "http://www.swagger.io/support"
    email: "support@swagger.io"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "example.com"
basePath: "/api/"

所以我的问题是如何生成OPEN API YAML文件，如：

openapi: 3.0.0
info:
  description: Some desc
  version: "1.0"
  title: Test rest project
  termsOfService: http://swagger.io/terms/
  contact:
    name: Rest Support
    url: http://www.swagger.io/support
    email: support@swagger.io
  license: …

我们有一些通过 Api 管理公开的 Azure Functions？Api Management 是否可以自动公开 /swagger 端点，就像 Swashbuckle 包对 Asp.Net 中的 api 所做的那样。

我在Express 中使用swagger-jsdoc。使用这个库来描述一个 api 端点，我在 YAML 的 JSDock 块中使用以下几行：

/**
 * @swagger
 * /users:
 *    post:
 *      summary: Register a user
 *      tags: [Users]
 *      description: Register a new user and return its cookie token (connect.sid)
 *      parameters:
 *        - in: body
 *          name: body
 *          schema:
 *            type: object
 *            required: [login, password, confirm]
 *            description: user's credential
 *            properties:
 *              login:
 *                type: string
 *                minLength: 3
 *                maxLength: 10
 *              email:
 *                type: string
 *              password: …

我正在运行 springdoc-openapi-maven-plugin，具有以下（标准）配置：

        <plugin>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-maven-plugin</artifactId>
            <version>0.2</version>
            <executions>
                <execution>
                    <id>integration-test</id>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>

该插件似乎运行，但没有输出。

我在 Maven 输出中收到 404 错误：

[INFO] --- springdoc-openapi-maven-plugin:0.2:generate (integration-test) @ paatinc-util-websrv ---
10:40:33.930 [http-nio-8080-exec-1] INFO  o.a.c.c.C.[Tomcat].[localhost].[/] - Initializing Spring DispatcherServlet 'dispatcherServlet'
10:40:33.931 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Initializing Servlet 'dispatcherServlet'
10:40:33.956 [http-nio-8080-exec-1] INFO  o.s.web.servlet.DispatcherServlet - Completed initialization in 25 ms
10:40:33.969 [http-nio-8080-exec-1] INFO  io.paat.util.filter.LoggingFilter - GET http://localhost:8080/v3/api-docs from 127.0.0.1
[ERROR] An error has occured: Response code 404

我可以从我的日志中看到 404 正在调用：http://localhost:8080/v3/api-docs

我还在 springdoc-openapi-maven-plugin 文档中看到以下配置：

 <configuration> …

我想弄清楚如何在 OpenAPI 中记录我的两个查询参数。

过滤

我的过滤遵循JSON:API的建议，例如采用以下形式：

• ?filter[post]=1,2,3
• ?filter[post]=1,2,3&filter[author]=5

该filter键是一个关联数组可以包含在我的API资源名称的一组列表。分配给每个过滤器键的值是单个 id 或逗号分隔的 id 列表。

排序

排序也遵循JSON:API 推荐，所以像这样：

• ?sort=age
• ?sort=age,-height

所述sort查询参数被分配一个排序字段或逗号分隔排序字段的列表的值。请注意，height字段前缀的减号表示降序排序。

题

我如何在 OpenAPI 中表示我的过滤和排序？

例如，我不确定是否可以指定过滤器键是关联数组，或者它接受逗号分隔的 id 列表。排序几乎相同的问题：如何表示以逗号分隔的排序字段列表？

我正在为 Web 服务定义通用模式，并且我想将它们导入到规范的组件/模式部分。我想创建一个跨多个服务通用的规范数据模型，以避免在每个服务定义中重新定义相似的对象。

有没有办法做到这一点？是否有与 XSD 对其导入标签所做的类似的机制？

我已经进行了广泛的谷歌搜索，但找不到一个好的工具来做到这一点。我能找到的最接近的是https://github.com/googleapis/gnostic，它允许将 OpenAPI 描述 (swagger.yaml) 转换为 .pb 文件或 .json 文件。我想知道是否有任何工具可以将此 .pb 文件转换为 .proto proto3 文件？

我也试过https://github.com/NYTimes/openapi2proto但不幸的是有一些情况没有正确处理。

在此先感谢您的帮助！

DRF文档提到了这一点：

请注意，当使用视图集时，基本文档字符串用于所有生成的视图。要为每个视图提供描述，例如列表和检索视图，请使用文档字符串部分，如架构作为文档：示例中所述。

但是链接不好，类似的链接https://www.django-rest-framework.org/api-guide/schemas/没有提到这些“部分”。

我如何在我的单个 Viewset 中清楚地记录我不同的可能的 REST 操作，当它组成时，

class ViewSet(mixins.ListModelMixin,                                            
              mixins.RetrieveModelMixin,                                        
              mixins.CreateModelMixin,                                          
              mixins.UpdateModelMixin,                                        
              ):       

我的原始用例：

我正在gRPC使用服务器（使用protobuf）在 GO 中构建应用程序，并将其包装在 HTTPS 服务器中（使用gin）。只有 HTTPS 服务器被发布到客户端使用（我的意思是我的应用程序可以通过 REST API 访问，实际上然后在 gRPC 端点上拨号），我使用SwaggerOpenAPI3发布它（版本 3 是主要的此处要求）规范。gRPC 和 HTTPS 都是必需的，任何解决方案都应遵循此架构。

我不想在两个地方维护我的服务器规范，即我不想同时维护 proto 文件 ( .proto) 和 swagger 规范 ( .json/.yaml)。由于我绝对必须编写 proto 文件来生成 gRPC 服务器，因此我想自动生成 swagger 规范（OpenAPI3）。

我在哪里：

我能够使用grpc-gateway库swagger从 protobuf 文件 ( .proto)生成OpenAPI2 规范，如下所示：grpc-rest-go-example。但我的要求是 OpenAPI3；更具体地说，我想使用OpenAPI3 中的功能并从proto 的功能映射到它。这在 OpenAPI2 中是不可能的，因为它不允许 API 具有多个类型定义的请求/响应主体，这是 OpenAPI3 中通过启用 oneOf、anyOf 和 allOf 构造添加的一项功能。oneOfoneof