【OpenAPI Docs】北极星 OpenAPI Docs 建设

[chuntaojun]

【OpenAPI Docs】北极星 OpenAPI Docs 建设

[onecer]

一期规划

目标

提供一个能用的swagger 文档可以在线测试

• 根据现有的接口丰富其API接口的文档描述
• 生成swagger2.0文档
• 提供swagger-ui 加载 北极星http api swagger2.0文档

实施步骤

• polaris-console加载swagger-ui 提供前端。
• 丰富API接口参数，为生成文档做准备。
• 用go-restful-openapi（目前只支持生成openAPI2.0）生成swagger2.0文档。

遇到的困难

1. 我们polaris数据struct是protobuf生成的，默认带有 Json tag ·omitempty· 会被忽略
2. protobuf的类型字段是一个结构·wrappers.StringValue· 它会被认为是嵌套的结构类型，也会被解析为结构，而我们不希望它被解析。
3. protobuf多余的字段，不希望展示的 state、sizeCache、unknownFields
4. 自定义json tag功能，可以筛除多余的字段和丰富json 描述 （放到2期）

具体issue polarismesh/go-restful-openapi#3

目前进度

目前针对遇到的困难 1、2、3做了些特别的处理具体看这个PR polarismesh/go-restful-openapi#1

目前一期处于推平阶段，需要补充好接口文档。

可以参考 已完成文档例子 #652

任务拆分

以下是推平需要补充文档的接口相关 ISSUE

• 【OpenApiDoc】config_server中的http接口添加Swagger的描述 #636
• 【OpenApiDoc】auth和client中的http接口添加Swagger的描述 #635
• 【OpenApiDoc】core_console_access中的http接口添加Swagger的描述 #634
• 【OpenApiDoc】maintain_access中的http接口添加Swagger的描述 #633
• 【OpenApiDoc】naming_console_access中的http接口添加Swagger的描述 #632

二期规划

目标

提供一个精准的swagger文档，并支持最新的openapi3.0 ，为mock生成和生成client sdk铺路。

1. 支持openapi3.0
2. 接口的Model更加精准，排除不必要的字段
3. 支持i18n

实施步骤

• 让go-restful-openapi支持生成Swagger3.0 或者 写函数或者调用包 将2.0格式转3.0
• 为api接口定义单独的文档用的 Struct或者让Protobuf生成只是自定义JSON Tag
• 定义相关的i18n文件，提供接口转换API名字、分组和描述等。

[Guo-Zhang]

1. 关于整体目标。

我们Python SDK项目这边需要可靠的OpenAPI和Mock。我的建议是把OpenAPI有一个可用API和Mock有一个可用API定义为阶段目标1和阶段目标2，这两个目标本身相对比较清晰简单，加起来刚好构成我们在例会上沟通的设想的Demo示例。

我不建议像目前一样同时进行很多个API的修补，而是应该集中精力先搞定一个、积累改造经验，然后再横向拓展、调动社区力量。

2. 对目前进展和问题的理解。

从描述看，主要问题在于原本的代码没有考虑到生成文档的需求，直接使用工具做有比较大的偏差。我这里是框架自带的特性，所以没有注意过这个问题。看起来代码重构的范围比我预想的要大。即使是修改一个API，也可以预期会遇到不小的问题。因此可以预期：

• 例会需要协调各个环节的分工，越精细越好。
• 整体重构的经验需要总结成开发者文档，让更多人可以follow文档参与进来。

3. 其他

目前的API其实设计很有问题，风格很不统一。我一直想提，理论上需要一个大版本对API进行一轮整改，让v2版本的API风格整体保持统一，v1版本逐步deprecate。如果这个事情要做，可以考虑把OpenAPI和Mock的特性随着v2版本一起发布，不一定需要在v1版本就搞定。当然也可以在v1到v2过渡的阶段先发出来验证。

我比较建议在后续的一些版本把新API、OpenAPI文档、Mock作为实验特性先放出来，然后在某个中版本或者大版本做成默认。参考Flutter和Dart的特性管理策略，比如Dart的空安全在2.7开始beta，在2.12默认，计划3移除非空安全特性（有明确时间表）。

[onecer]

一开始动机和目标主要有两个

• 可靠的openAPI3.0，来用openapi-generator生成python sdk，所以前面规划的一期和二期目标其实就是为了支持这个。
• 有个图形界面，既能看API文档，又可以自己动手可以在图形界面尝试调用API来观测数据。

1. 关于目标的确立

由于我们框架目前只支持的openAPI生成，而我们的数据结构又是protobuf生成的，和原生的go struct有点不一样，框架没有支持这个，要改造可能遇到的问题会不少。一开始也考虑过是否手动维护一个openapi3.0，可能两者代价差不多。后面和 @chuntaojun 进行了简单的讨论，想优先考虑尝试下框架生成。

目前而言，遇到的问题还是有的，比如response的信息，我们的返回结构比较难生成，要组合出好用的response还是挺费劲的。至此，没有规范这些的前提，前期要配合框架的插件生成的难度肯定是大于手动维护openapi3.0的。

但是兜底方案也有，代价都差不多，欢迎讨论和给意见。

• 重新定义函数内的结构来专门给文档用来生成。
• 在生成的基础上，手动补充成一个可靠的openAPI文件。
• 手动维护可靠的openAPI3.0，一步到位，是没什么难度，只有工作量，这个比较好量化。

至于2. 提到的分工，如果走生成的路线，主要后面遇到的困难还未完全知道，比如go-restful-openapi支持生成openapi3.0的工作量，所以暂时不知道怎么分工，欢迎提供建议。

3. 对API升级这个影响范围很大，周期长，所以现在主要是探讨在现有条件下快速提供一个可用文档，然后逐步完善它。

[onecer]

对于这个建设的目标还有别的补充的么

[Guo-Zhang]

手动维护适合走 API Design First的流程，即先做API设计并形成API文档，然后对应实现。我个人是比较偏好这种，不过对于北极星的情况来说可能没有必要。

框架生成是典型的Code First。这种对于北极星的情况是比较适宜的。走这条路线，从你目前的进展看，不可避免要对主项目的全局进行一定程度的重构，让后续开发可以适配OpenAPI。

我说的分工的意思是，业务逻辑的开发者和OpenAPI文档的维护者之间需要密切的协调，需要约定如何配合文档生成需求重构代码。

[onecer]

手动维护适合走 API Design First的流程，即先做API设计并形成API文档，然后对应实现。我个人是比较偏好这种，不过对于北极星的情况来说可能没有必要。

框架生成是典型的Code First。这种对于北极星的情况是比较适宜的。走这条路线，从你目前的进展看，不可避免要对主项目的全局进行一定程度的重构，让后续开发可以适配OpenAPI。

我说的分工的意思是，业务逻辑的开发者和OpenAPI文档的维护者之间需要密切的协调，需要约定如何配合文档生成需求重构代码。

关于mock和sdk生成，我觉得或许可以先拿一组API，先进行mock和sdk生成的实践，不用等全部接口都转换成openAPI3.0再行动。像kubernetes-client python用openapi generate，还是有很多工作要做的。
然后生成sdk的和mock的用到的openapi可以作为我们生成文档的最低要求，也可以倒逼文档的完善和规范。 按照openapi的标准，目前我们在reponse生成这块缺失比较多，也是有方案可以补充，善需实践来权衡利弊再决定。

文档生成协调这块，后面是要实践出一个适合我们的方案后，再出一个规范和文档，然后通过review慢慢规范起来。现在其实还是处于摸索当中的状态。