Open tskdsb opened 5 years ago
/assign @ddysher
Thanks for bringing this up.
Most of the questions here are related to representation of API docs, which are actually not part of nirvana. We use https://github.com/Rebilly/ReDoc for navigating APIs, can u explore it and see if it solves ur problem?
If so, then we can either upgrade ReDoc, or we put some rules in nirvana to force people writing more documentations (and thus better API docs).
/cc @kdada
Q: Required or Default?
A: If a parameter has a default value, it shows the default value in the field frame. Otherwise it shows Required
.
Q: Where is parameter descriptions?
A: In Parameter.Description
and Result.Description
. Also you can write comments for your struct fields. These comments will be shown at the right side of struct fields.
Q: How to set examples?
A: In Definition.Examples
. You can put response struct examples here now (No requests support).
I think we can improve the user experiences via implementing these features:
Definition.Examples
to support parameters. (Depends on ReDoc)Q: Required or Default? A: If a parameter has a default value, it shows the default value in the field frame. Otherwise it shows
Required
.Q: Where is parameter descriptions? A: In
Parameter.Description
andResult.Description
. Also you can write comments for your struct fields. These comments will be shown at the right side of struct fields.Q: How to set examples? A: In
Definition.Examples
. You can put response struct examples here now (No requests support).I think we can improve the user experiences via implementing these features:
- Implement documents server to proxy test requests to backend server.
- Refine
Definition.Examples
to support parameters. (Depends on ReDoc)
【有无默认值】和【是否必须项】概念上是不同的,但是在业务中一般都是【有默认值用默认值】,【无默认值手工填】,所以这两个flag可以简化为一个,同意。
Parameter.Description
我会去试试。body中的字段描述,comments是写在struct的tag中吗,比如这样:
type Tsk2 struct {
A string `json:"a" comments:"xxx"`
}
关于测试样例:我理解目前nirvana是有一个矛盾,Examples里只放了response,然后request是另外起服务还是加入到nirvana中?我建议是另外搞,顺便把response也拿出来,因为我们对ReDoc有依赖,不能受制于人,就让ReDoc用来【显示】,【交互】我们自己做。
For comments:
type Tsk2 struct {
// Write comments here.
A string `json:"a"`
}
If you are interesting in extending doc server for Nirvana, please write down your proposal.
经过 @kdada 的指导,更深入的使用后,发现nirvana的API生成已经足够完备,至少信息展示方面已经足够了。
那只剩【交互】方面的问题了,简单的说需要以下功能:
结构图:
方案:
待补充
@kdada
Can we update the docs so people can understand how to create useful API generation without asking :)
经过 @kdada 的指导,更深入的使用后,发现nirvana的API生成已经足够完备,至少信息展示方面已经足够了。
@zcong1993 How does it implement proxy and mock APIs?
@ddysher I'll update the doc when I'm free.
/kind feature
What happened: I'm glad to see the feature: api-auto-generation, it looks like: it seems good, but I want more.
What you expected to happen: I wrote an API documentation a few days ago, and I suffered a lot. So, I hope that the ability of API-generation can be more complete:
可能废话有点多,所以这里在总结一下,要求一共两点: