[Summer 2022] Nacos新增规范化的2.0版OpenAPI接口

[realJackSun]

Background

Nacos has been popular by users and developers since its open source. After 3 years of development, Nacos has now released version 2.1.0. However, due to the irregularities of the early project, the HTTP OpenAPI used by Nacos in version 0.X and version 1.X has many non-standard usage methods; for example, the return content is missing, the return body format is not uniform, and there are no error codes.

And due to Nacos 2.X version needs to be compatible with the Nacos 1.X client, these old openAPIs cannot modify their return content to prevent incompatibility; but Nacos also needs a unified and standardized openAPI, which is convenient for new users Connect Nacos with the system and increase the readability of openAPI.

Therefore, it is necessary to redesign a set of openAPI of version 2.0 to gradually replace the openAPI of v1 version. And add the openAPI of version 2.0 for some new operations, such as query by IP latitude, connection query, etc.

Target

Choose an API style, design the corresponding response body and use it to reconstruct OpenAPI version 2.0, and add openAPI with new version functions.

Difficulty

Basic

Mentor

@KomachiSion
[email protected]

Output Requirements

• Choose a common API style like RestFul or RPC style.
• Design the response body of OpenAPI, such as error code, data, message information, etc.
• Refactor all necessary old version openAPI, such as registering services, publishing configuration, etc., using the new style and response body.
• Add the openAPI of version 2.0 functions, such as querying services by IP alone, etc., using the new style and response body
• Add the content of version 2.0 openAPI in the official Nacos documentation.

Technical Requirements

• Familiar with common OpenAPI specifications and styles
• Familiar with Java programming language
• Familiar with Spring, Spring boot and SpringMvc
• Familiar with writing MacDown documents
• Understand HTTP protocol and specifications

---

背景

Nacos 自开源起，深受广大用户和开发者喜爱，经过3年的开源发展，如今Nacos已经发布了2.1.0版本。但由于早起项目的不规范，Nacos在0.X版本以及1.X版本所使用的HTTP OpenAPI存在很多不标准的使用方式；如返回内容缺失，返回体格式不统一，无错误码等问题。

由于Nacos2.X版本需要兼容Nacos 1.X版本的客户端，因此这些旧的openAPI不能修改其返回内容，以防止出现不兼容的情况；但Nacos同时又需要一个统一的规范化的openAPI，方便新用户和系统对接Nacos，并增加openAPI的可读性。

因此需要重新设计一套2.0版本的openAPI，逐渐替代v1版本的openAPI，并为部分新的操作添加2.0版本的openAPI，如按照Ip纬度查询、连接查询等。

目标

选择一种API风格，设计对应返回体规范并用其重构出2.0版的OpenAPI，并添加新版本功能的openAPI。

难度

基础

导师

@KomachiSion
[email protected]

产出要求

• 选择一种常见且通用的API风格，如RestFul或RPC风格。
• 设计OpenAPI的返回体规范，如错误码，数据，message信息等。
• 使用新风格和返回体规范，重构所有必要的旧版本openAPI，如注册服务，发布配置等。
• 使用新风格和返回体规范，新增2.0版本功能的openAPI，如按照IP唯独查询服务等。
• 在Nacos的官方文档中，添加2.0版本openAPI的内容。

能力要求

• 熟悉常见OpenAPI规范及风格
• 熟悉Java编程语言
• 熟悉Spring，Spring boot及SpringMvc
• 熟悉编写MacDown文档
• 了解HTTP协议及规范

[realJackSun]

Nacos新增规范化的2.0版openAPI接口，并增添相应的文档。

[zhicheng-ning]

哈喽，我有个疑问，MacDown 只是 MacOS 下的一款 markdown editor，项目要求应该是熟练 Markdown 写作，不一定是必须要用 Macdown 吧，比如说可以用 Typora ？

[rookie-ricardo]

@Ax-For 我看到了您在这个 issue 下面提了很多代码，我正好也在关注这个 issue，我发现您的一些的命名很不规范，比如一个 Controller 的入参应该是 Form 而不是 VO，VO一般是指返回的视图对象，既然是一个新版本的 API，我希望我们能把规范也做好一点，我本地已经改了相关代码，但是还没有提 PR，我是想先和您讨论这个问题，不知我的建议您是否认可？