英文:
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
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论