什么是公共模型

  • 在API设计过程中,为了促进数据一致性和复用性,CodeArts API提供了强大的“公共模型”功能。这一特性允许设计者在定义API的请求体(Body)或响应内容时,便捷地引用已预设的标准化数据结构。

    公共模型类型包括以下七类公共模型定义:

    数据模型

    公共响应

    公共参数

    公共请求体

    公共示例

    安全模型

    公共响应头

    这一特性不仅提升了API设计的效率,还确保了不同API间数据格式的统一性,简化了维护工作。无论是构建基础的数据结构,还是设定通用的响应模板、安全规则乃至示例数据,开发者都能依托这些公共模型快速实现,从而专注于业务逻辑的创新与优化。

数据模型

数据模型类似于编程语言中的数据结构,在API设计时主要应用于 “返回响应”和json/xml类型的“Body参数”。在设计API的请求体或响应内容时,开发者可直接引入公共的数据模型,实现数据结构的即时复用。此外,还提供在数据模型的文档页面直观查看所有引用该模型的API及其它模型,从而加深了模块间透明度,促进了设计的一致性和维护的便利性。

公共响应

公共响应,默认遵循“application/json”格式,旨在提供统一且规范的返回结果。在设计API的响应体时,开发者能够引用已有的公共响应模板,以此加快开发进程并确保响应信息的标准化。

每项公共响应的文档页面均详尽展示了所有引用该响应的API列表,便于维护与升级,从而提升了整个API生态的协同效率与信息管理的清晰度。

公共参数

在API设计环节中,公共请求参数扮演着基础而灵活的角色,支持配置于“query”(查询字符串)、“path”(路径)或“header”(头部)等多个位置,以适应多样化的接口需求。开发者能够直接调用预定义的公共参数,有效加速了请求参数的标准化构建过程。此外,每个公共参数的文档页面均汇总了所有引用该参数的API列表,极大增强了参数管理和接口文档的透明度,便于开发者进行高效维护与协同作业。

公共请求体

在接口设计中,公共请求体默认“application/json”格式。开发者能够便捷地复用已定义的公共请求体,直接应用于API的Body部分,显著提升了开发效率与数据结构的一致性。且公共请求体文档页面也详尽展示了所有引用该请求体的API,便于后期维护。

公共示例

公共示例允许在API的请求体实例与响应结果示例中灵活引用,确保了示例数据的统一性和准确性。在公共示例文档页面还清晰罗列了所有引用该示例的API,便于后期维护。

安全模型

安全模型提供“http”、“apikey”、“oauth2”、“openIdConnect”四种类型。选择不同类型的安全模型后,需要在方案内容中填写必要的配置信息,然后用于API设计中“安全方案”的引用。此外,每个安全模型的文档页面展示了所有引用该模型的API清单,便于后期维护。

公共响应头

公共响应头旨在简化并标准化API“返回响应”中的头部信息配置。API设计过程中,开发者能够直接引用已定义的公共响应头至响应头设置中,促进了响应格式的一致性和管理的高效性。此外,每个公共响应头的文档页面都详细列出了所有引用该响应头的API,便于后期维护。