How to generate API docs with openapi-generator.tech

huangapple go评论85阅读模式
英文:

How to generate API docs with openapi-generator.tech

问题

我正在使用https://openapi-generator.tech/进行尝试,并且我有一个示例的openapi.yaml文件:

openapi: 3.1.0

info:
  title: 示例API
  description: 我惊人的描述。
  version: 0.0.9

servers:
  - url: http://localhost:8080/v1
    description: 我惊人的服务器描述。

paths:
  /users:
    get:
      summary: 返回所有用户的列表。
      description: 我惊人的/users端点描述。
      responses:
        "200":
          description: (OK) 用户对象的JSON数组。
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

我尝试了以下生成命令:

openapi-generator-cli generate -g go-gin-server --global-property=apiDocs=true -i ./openapi.yaml

无论是带有--global-property=apiDocs=true部分还是不带都尝试过。但是都没有生成/api/doc/docs端点。

我做错了什么?

请注意,服务器正常运行,即我可以使用curl命令访问yaml文件中指定的端点。

英文:

I am playing around with https://openapi-generator.tech/ and I have an example openapi.yaml file:

openapi: 3.1.0

info:
  title: Sample API
  description: My amazing description.
  version: 0.0.9

servers:
  - url: http://localhost:8080/v1
    description: My amazing server description.

paths:
  /users:
    get:
      summary: Returns a list of all users.
      description: My amazing /users endpoint description.
      responses:
        "200":
          description: (OK) A JSON array of user objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

I have tried the following generation command:

openapi-generator-cli generate -g go-gin-server --global-property=apiDocs=true -i ./openapi.yaml

both with, and without the --global-property=apiDocs=true part. Neither case generated an /api, /doc, or /docs endpoint.

What am I doing wrong?

Note that the server runs fine, i.e., I can curl the endpoints specified in the yaml file.

答案1

得分: 1

看起来 go-gin-server 服务器存根生成器不支持添加这种类型的端点。如果你查看这个生成器使用的路由模板,你会发现除非在规范中定义了 /api/doc/docs 端点,否则没有任何配置选项会生成这些端点。

我不太清楚你对这个端点的期望是什么,但你可以在规范中定义其中一个端点,并实现你想要的行为,或者你可以自定义模板,在代码生成过程中自动添加这个端点。

英文:

It doesn't look like the server stub generator go-gin-server supports adding this type of endpoint. If you look at the routers template that this generator uses you can see that no config option will generate an /api, /doc or /docs endpoint unless you have defined it in your spec.

It's not clear to me exactly what you are expecting from this endpoint, but you could define one of these endpoints in your spec and implement the behavior you would like, or you could customize the template to automatically add this endpoint during code generation

huangapple
  • 本文由 发表于 2022年11月2日 22:00:02
  • 转载请务必保留本文链接:https://go.coder-hub.com/74290420.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定