标签: openapi

https://www.dariawan.com/tutorials/spring/documenting-spring-boot-rest-api-springdoc-openapi-3/

试图遵循这些

我如何处理像这样的注释

@ApiModel(value = "Response container")

@ApiModelProperty(value = "Iventory response", required = true)

虽然我已经看到了OpenAPI规范中的示例:

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'

Run Code Online (Sandbox Code Playgroud)

我不明白为什么使用additionalPropertiesMap是地图/字典的正确模式.

这个规范唯一具体的内容additionalProperties也是没有用的:

以下属性取自JSON Schema定义,但其定义已调整为Swagger规范.它们的定义与JSON Schema中的定义相同,只有在原始定义引用JSON模式定义的情况下,才使用模式对象定义.

• 项目
• 所有的
• 性能
• additionalProperties

如何在springdoc-openapi-ui (OpenAPI 3.0 /swagger-ui.html) 中为不记名令牌认证启用“授权”按钮，例如 JWT。

Spring@Controller和@Configuration类需要添加哪些注解？

引用OpenAPI 2.0,模式对象或Swagger 2.0,模式对象以及discriminator字段定义:

添加对多态性的支持.鉴别符是架构属性名称,用于区分继承此架构的其他架构.必须在此模式中定义使用的属性名称,它必须位于required属性列表中.使用时,值必须是此架构的名称或继承它的任何架构.

我的困惑/问题:

• 这对我来说是模棱两可的,它在继承或多态性中起到了什么样的作用.有人可以discriminator用一个工作实例来解释它究竟做了什么以及如果我们不使用它会怎样？某些操作依赖于它的任何错误,警告或任何工具？
• 是不是swagger-editor不支持discriminator,并且这个字段用于其他一些工具？

到目前为止我尝试了什么:

• 我试图使用swagger编辑器和相同文档中的示例(也在下面提到),来玩这个属性,看看我是否可以看到它的任何特殊行为.我更改了属性,删除了它,并将Dog模型扩展到更深层次并在新的子模型上尝试相同,但我没有看到swagger-editor预览中的任何更改.
• 我尝试在线搜索,特别是stackoverflow问题,但没有找到任何相关信息.

我用来做实验的示例代码:

definitions:
  Pet:
    type: object
    discriminator: petType
    properties:
      name:
        type: string
      petType:
        type: string
    required:
    - name
    - petType
  Cat:
    description: A representation of a cat
    allOf:
    - $ref: '#/definitions/Pet'
    - type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          default: lazy
          enum:
          - clueless
          - lazy …

带有 springdoc-openapi-ui (Swagger UI) 的 Spring Boot 2.2 应用程序运行 HTTP 端口。该应用程序部署到 Kubernetes，并通过 Ingress 将 HTTPS 请求从集群外部路由到服务。

在这种情况下，可用的 Swagger UIhttps://example.com/api/swagger-ui.html有错误的“生成的服务器 url”- http://example.com/api。虽然应该如此https://example.com/api。

虽然 Swagger UI 通过 HTTPS 访问，但生成的服务器 URL 仍然使用 HTTP。

我注意到在OpenAPI 路径项和其他一些构造中都有summary和description字段，它们之间有什么区别，每个的目的是什么？对我来说，他们似乎完成了同样的事情，但我在文档中没有找到任何与此相关的内容。乍一看，这似乎是一个无意义的问题，但由于您可以使用 OpenApi 生成 API 代码，在文档等中使用它。我认为澄清这些目的是有意义的。

在swagger文件对象中声明日期的正确方法是什么？我认为它是:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date

但我看到很多这样的声明:

  startDate:
    type: string
    description: Start date
    example: "2017-01-01"
    format: date
    pattern: "YYYY-MM-DD"
    minLength: 0
    maxLength: 10

谢谢.

我在c#中有一个Asp.Net Web API 5.2项目,并使用Swashbuckle生成文档.

我有一个包含继承的模型,比如从Animal抽象类中获取Animal属性,从中派生出Dog和Cat类.

Swashbuckle只显示Animal类的模式,所以我尝试使用ISchemaFilter(他们也建议),但我无法使它工作,我也找不到合适的例子.

有人可以帮忙吗？

我想用Swagger POST一个json体,像这样:

curl -H "Content-Type: application/json" -X POST -d {"username":"foobar","password":"xxxxxxxxxxxxxxxxx", "email": "foo@bar.com"}' http://localhost/user/register

目前,我有这个定义:

"/auth/register": {
        "post": {
            "tags": [
              "auth"
            ],
            "summary": "Create a new user account",
            "parameters": [
                {
                    "name": "username",
                    "in": "query",
                    "description": "The username of the user",
                    "required": true,
                    "type": "string"
                },
                {
                    "name": "password",
                    "in": "query",
                    "description": "The password of the user",
                    "required": true,
                    "type": "string",
                    "format": "password"
                },
                {
                    "name": "email",
                    "in": "query",
                    "description": "The email of the user",
                    "required": true,
                    "type": "string",
                    "format": …

这里说我可以引用另一个文件中的定义来获取单个路径，但该示例似乎引用了整个文件，而不是对象下的单个路径定义paths。如何在另一个文件的paths对象中分配单独的路径？

例如，我有Anotherfile.yaml包含路径/a/b：

paths:
  /a/b:
    post:

在另一个文件中，我使用如下方式$ref引用路径：/a/b

paths:
  /c/d:
    $ref: 'Anotherfile.yaml#/paths/a/b'

但这给出了一个错误：

在 ./Anotherfile.yaml 的内容中找不到路径/a/b