无论哪种类型的Web API, 都可能需要给其他开发者使用. 所以API的开发者体验是很重要的. API的开发者体验, 简写为 API DX (Developer Experience)....有时候API会被错用, 甚至带来毁灭性后果. 最后抱怨该API等用户越来越多, 慢慢的, 客户就会停止使用该API.
API的目的是让人们可以简单的使用它来达到自己的目的....用户就是上帝, 为用户设计API
和构建任何东西一样, 你需要一个计划, 你需要在真正做之前来决定你想要的是什么. API 设计也是一样的.
API 并不是用来盲目的暴露一些数据或业务处理能力....API描述格式会为API提供一个标准化的描述, 并且它很像代码. 它的优势主要有:
有助于在项目团队中共享设计
了解这种格式的人或者工具可以很简单的理解它....使用OpenAPI 和 JSON Schema 来描述 API 的数据
OAS 依赖于 JSON Schema 标准来对所有的数据(查询参数, body 参数, 响应body等)进行描述.