[API generation] we need better api generation
tskdsb opened this issue · comments
/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：
- 所有方法按钮可点击（如GET，POST），提供交互体验（主要用于前端对API进行检验，以便修改前端代码，当然后端也可以用，方便自验）
- 界面更精简，突出重点
- 【外观】左侧目录保留，右侧一页一个API
- 【输入输出】参数按照位置（path，head，query，form，body等）一路列下来，使用不同颜色背景框，最后列出response，每个参数标明【是否必填】【有无默认值】【前端类型】【参数用途？意义？描述？】(request和response中的body，每个字段鼠标停留可查看详情)，写这么详细是为了减少前端看了API文档后还带着不理解来找后端的次数，减少沟通成本，也让后端在定义参数与字段时更加用心。
- 【测试样例】在提供API的同时提供一套或多套【请求-响应对】，其中请求可以帮助快速上手（好的教程一般都是【详细说明+简单例子】），响应可以用于检测返回。流程可以按照【查：404】》【增：201/202】》【查：200】》【改: 200】》【查：200】》【删：202】》【查：404】这样的步骤进行。这样每次前后端修改完代码，就可以自动跑一下这套例子，避免了【写代码10分钟，自测半小时】的低效情况。
可能废话有点多，所以这里在总结一下，要求一共两点：
- 界面简洁，信息完整
- 提供交互，提供样例
/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:
- Implement documents server to proxy test requests to backend server.
- Refine
Definition.Examplesto 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 showsRequired.Q: Where is parameter descriptions?
A: InParameter.DescriptionandResult.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: InDefinition.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.Examplesto 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生成已经足够完备，至少信息展示方面已经足够了。
那只剩【交互】方面的问题了，简单的说需要以下功能：
- 为所有parameters增加输入框
- 方法可点击（如POST，GET），点击发送请求
- 响应可显示（可以显示在原来example的地方）
- 样例可保存（一次典型的请求响应数据可以保存下来当测试用例使用）
结构图：
方案：
- 选取ReDoc某个版本固化，在此基础上修改，增加上面提到的4个功能
- 自动化接口测试同时建设起来
待补充
@zcong1993 How does it implement proxy and mock APIs?
@ddysher I'll update the doc when I'm free.
