sap-api-style

SAP API 风格指南

相关技能

• sap-cap-capire：用于 OData 服务文档、CAP API 模式和服务定义标准
• sap-fiori-tools：用于 API 使用模式、Fiori 应用集成和 OData 最佳实践
• sap-abap：用于编写 ABAP API 文档、实现 REST 服务或遵循 API 设计模式
• sapui5：用于前端 API 集成、OData 使用和 UI 服务模式
• sap-btp-cloud-platform：用于 BTP 服务 API 文档和集成模式

目录

1. 概述
2. 何时使用此技能
3. 快速决策树
4. 核心原则
5. 快速参考表
6. 可用模板
7. 参考文件
8. 使用说明
9. 应避免的常见陷阱
10. 外部资源
11. 更新和维护
12. 常见问题

概述

此技能提供全面的指南，帮助你按照 SAP API 风格指南的官方标准编写 SAP API 文档。内容涵盖 SAP 生态系统中使用的所有主要 API 类型和文档编写方法。

文档来源：https://github.com/SAP-docs/api-style-guide（已提取 76 个文件）

何时使用此技能

在以下情况下使用此技能：

• 创建 API 文档，涵盖 REST、OData、Java、JavaScript、.NET 或 C/C++ API
• 编写 OpenAPI 规范，用于 SAP API Business Hub
• 检查 API 名称是否符合 SAP 命名约定
• 编写 API 参数、响应和操作的文档，并采用正确的格式
• 使用 SAP 模板创建手动 API 文档
• 在源代码中编写文档注释（Javadoc、JSDoc、XML 注释）
• 根据 SAP 生命周期政策实施 API 弃用
• 编写开发者指南或服务文档
• 对 API 文档执行质量检查
• 将 API 发布到 SAP API Business Hub

快速决策树

API 类型是什么？

REST/OData API
├─ Auto-generated (OpenAPI/Swagger)?
│  └─ references/rest-odata-openapi-guide.md
│     • OpenAPI specification standards
│     • Package, API, operation descriptions
│     • Parameters, responses, components
│     • SAP API Business Hub requirements
│
└─ Manually written?
   └─ references/manual-templates-guide.md
      • REST templates (2-level: overview → method)
      • OData templates (3-level: service → resource → operation)
      • Complete field requirements
      • templates/ directory for ready-to-use files

Native Library API
├─ Java → references/java-javascript-dotnet-guide.md
├─ JavaScript → references/java-javascript-dotnet-guide.md
├─ .NET (C#) → references/java-javascript-dotnet-guide.md
└─ C/C++ → references/java-javascript-dotnet-guide.md
    • Documentation comments structure
    • Language-specific tags
    • Templates for classes, methods, enums
    • Complete code examples

要执行什么任务？

Naming
└─ references/naming-conventions.md
   • REST/OData naming (resources, parameters, URIs)
   • Native library naming (classes, methods, constants)
   • Common mistakes to avoid

Writing Descriptions
└─ references/rest-odata-openapi-guide.md
   • Package descriptions
   • API details (info object)
   • Operations, parameters, responses

Quality Assurance
└─ references/quality-processes.md
   • Complete API Quality Checklist
   • Review workflows
   • Development team guidelines

Deprecating APIs
└─ references/deprecation-policy.md
   • Lifecycle states (beta, active, deprecated, decommissioned)
   • Timeline requirements (12+ months support)
   • Required metadata (x-sap-stateInfo)

Developer Guides
└─ references/developer-guides.md
   • Structure guidelines
   • Content selection
   • Code sample standards

核心原则

1. SAP API 之间保持一致

所有 SAP API 文档都遵循一致的约定：

• 命名：因语言而异（camelCase、PascalCase、kebab-case）
• 结构：采用分层结构，导航清晰
• 格式：句子以大写字母开头，以句号结尾
• 语言：美式英语

2. API 类型专属标准

API 类型	标准	工具	文档
REST	OpenAPI 3.0.3	Swagger	规范
OData	v4.01、v3.0、v2.0	各种工具	OData.org
Java	Javadoc	javadoc	Oracle
JavaScript	JSDoc 3	jsdoc	JSDoc.app
.NET	XML 注释	DocFX	Microsoft
C/C++	Doxygen	doxygen	Doxygen.nl

3. 渐进式信息呈现

文档按层次组织：

• 高级概述提供背景信息和导航
• 详细参考资料涵盖特定 API、方法和操作
• 示例和模板展示实际用法

4. 质量标准

所有文档都必须：

• ✅ 由用户协助（UA）开发者审阅
• ✅ 使用一致的命名和术语
• ✅ 完整描述参数和响应
• ✅ 避免在示例中使用敏感数据
• ✅ 提供可运行的代码示例
• ✅ 确保链接和交叉引用准确无误

快速参考表

字符数限制

元素	限制	用途
API 标题	80	OpenAPI 中的 info.title
API 简短文本	180	x-sap-shortText
软件包简短描述	250	软件包磁贴描述
操作摘要	255	操作摘要行
描述	1024	一般描述

API 命名规则

通用规则（适用于所有 API 类型）：

• ❌ 名称中不要包含“API”：“Custom Forms API” → ✅ “Custom Forms”
• ❌ 不要使用“SAP”前缀：“SAP Document Approval” → ✅ “Document Approval”
• ❌ 不要使用动词：“Configuring Portal” → ✅ “Portal Configuration”
• ✅ 正确使用首字母大写
• ✅ 避免使用技术细节（REST、OData 等）

完整的语言专属规则请参见 references/naming-conventions.md。

常见文档标签

Java/JavaScript：

• @param <name> <description> - 参数文档
• @return <description> - 返回值
• @throws <class> <description> - 异常
• @deprecated <description> - 弃用通知

.NET：

• <summary> - 简要描述
• <param name=""> - 参数
• <returns> - 返回值
• <exception cref=""> - 异常

完整的标签参考请参见 references/java-javascript-dotnet-guide.md。

API 生命周期状态

状态	定义	支持	必需元数据
Beta	生产前测试	不作保证	state: beta
Active	已可用于生产环境（默认）	全面支持	可选
Deprecated	已由后继版本取代	12 个月以上	state、deprecationDate、successorApi
Decommissioned	已完全退役	无	记录移除情况

完整的时间线和流程要求请参见 references/deprecation-policy.md。

大型参考文档搜索路由

加载大型参考文档前，先搜索。使用 rg -n "<resource|operation|parameter|description|template|deprecation|x-sap-stateInfo>" references/*.md 定位确切规则，然后仅打开相关摘录。

• 手动编写 REST/OData 文档模板请使用 references/manual-templates-guide.md。搜索 REST API Template、OData Operation Template、field requirements、method 或资源名称。
• OpenAPI、OData、操作描述、响应、参数以及 SAP API Business Hub 发布检查请使用 references/rest-odata-openapi-guide.md。
• 资源、操作、软件包、类、方法、参数、枚举和常量的命名请使用 references/naming-conventions.md。
• Javadoc、JSDoc、XML 文档注释和原生 SDK 文档标签请使用 references/java-javascript-dotnet-guide.md。
• 生命周期状态、迁移指南和 x-sap-stateInfo 请使用 references/deprecation-policy.md。
• 审查清单、关卡和文档质量工作流请使用 references/quality-processes.md。

可用模板

templates/ 目录中提供可直接使用的模板：

REST API 模板（2 层）

1. rest-api-overview-template.md - 资源级概览
2. rest-api-method-template.md - 单个端点详情

OData API 模板（3 层）

1. odata-service-overview-template.md - 完整服务概览
2. odata-resource-template.md - 单个资源/实体集
3. odata-operation-template.md - 特定操作详情

所有模板均包含：

• 清晰的“使用方法”说明
• 可自定义的[占位文本]
• 完整的章节结构
• 可运行的示例
• 行内指南

参考文件

完整指南

1. rest-odata-openapi-guide.md（2,800 行）

   • 完整的 OpenAPI 规范指南
   • 软件包、API 和操作说明
   • 参数、响应和组件
   • 安全方案、标签和外部文档
   • 字符数限制和反模式

2. manual-templates-guide.md（2,765 行）

   • REST API 模板（2 级层次结构）
   • OData API 模板（3 级层次结构）
   • 完整的模板结构
   • 各字段要求
   • 最佳实践和示例

3. naming-conventions.md（2,059 行）

   • REST/OData 命名规则（资源、参数、URI）
   • 原生库命名（类、方法、常量、软件包）
   • 特定语言的约定
   • 常见错误及修正方法
   • 决策树和参考表

4. quality-processes.md（1,774 行）

   • 完整的 API 质量检查清单
   • 审核工作流（开发人员与 UA 协作）
   • 开发团队指南
   • 常见审核发现及解决方案
   • 流程图

5. java-javascript-dotnet-guide.md（1,517 行）

   • 文档注释结构
   • 特定语言的标签（Java、JavaScript、.NET、C/C++）
   • 类、方法和枚举的模板
   • 完整的代码示例
   • 各语言的最佳实践

6. developer-guides.md（704 行）

   • 指南结构标准
   • 主题类型（概念、参考、任务）
   • 内容选择标准
   • 代码示例标准（可编译、简洁、有注释）
   • 最佳实践

7. deprecation-policy.md（664 行）

   • API 生命周期状态（测试版、活跃、已弃用、已停用）
   • 时间要求（支持 12 个月以上，生命周期 24 个月以上）
   • 必需的元数据（x-sap-stateInfo、artifact.json）
   • 停用流程
   • 完整示例

8. glossary-resources.md（472 行）

   • 完整的术语定义（API、OData、OpenAPI 等）

   • 外部资源链接（标准、工具、SAP 资源）

   • 快速参考表

   • 工具文档链接

   • 内容提取和整理跟踪

   • SAP 文档的源文件映射

   • 整合和改编说明

捆绑资源

此技能包含全面的文档和模板，并按最佳使用方式进行组织：

参考指南（references/）

• 9 个详细的参考文件（共 10,861 行）
• 全面覆盖 SAP API 风格指南标准
• 渐进式披露架构，可高效加载

模板文件（templates/）

1. rest-api-overview-template.md（217 行）——第 1 级 REST 概述
2. rest-api-method-template.md（477 行）——第 2 级 REST 方法详情
3. odata-service-overview-template.md（411 行）——第 1 级 OData 服务
4. odata-resource-template.md（557 行）——第 2 级 OData 资源
5. odata-operation-template.md（681 行）——第 3 级 OData 操作

总计：2,343 行可直接使用的模板

使用说明

第 1 步：确定 API 类型

确定你要编写文档的是 REST、OData、Java、JavaScript、.NET 还是 C/C++ API。

第 2 步：选择方式

自动生成：在源代码中编写文档注释 → 使用适当的标签 → 提交审核

手动编写：从 templates/ 中选择模板 → 自定义[占位符] → 遵循层次结构 → 使用检查清单进行验证

第 3 步：应用标准

查阅适当的参考文件：

• 命名：naming-conventions.md
• 说明：rest-odata-openapi-guide.md 或 java-javascript-dotnet-guide.md
• 质量：quality-processes.md
• 弃用：deprecation-policy.md

第 4 步：质量检查

发布前：

1. 对照 API 质量检查清单进行审核（quality-processes.md）
2. 验证命名约定（naming-conventions.md）
3. 检查字符数限制（参见上方的快速参考表）
4. 确认示例中不含敏感数据
5. 测试所有代码示例
6. 确认链接有效
7. 获取 UA 开发人员审核

第 5 步：发布

• REST/OData：提交至 SAP API Business Hub
• Java/JavaScript/.NET：使用相应工具生成（Javadoc、JSDoc、DocFX）
• 开发者指南：发布至 SAP Help Portal 或产品文档

应避免的常见问题

命名：

• ❌ 包含“API”：“Custom Forms APIs” → ✅ “Custom Forms”
• ❌ 使用“SAP”前缀：“SAP Document Approval” → ✅ “Document Approval”
• ❌ 使用动词：“Configuring Portal” → ✅ “Portal Configuration”

描述：

• ❌ 使用第二人称：“This operation creates...” → ✅ “Creates a new user”
• ❌ 使用笼统的响应：“No content” → ✅ “Product is out of stock”
• ❌ 在描述中重复摘要

文档：

• ❌ 跳过 UA 审核
• ❌ 在示例中包含敏感数据
• ❌ 缺少必需的标签
• ❌ 术语不一致

请参阅各参考文件，了解完整的反面示例及修正方法。

常见问题

问题	修正方法
API 名称使用动词或多余的“API”后缀	编写描述前，先应用 references/naming-conventions.md 中的命名规则。
OpenAPI 描述过于笼统	使用 references/rest-odata-openapi-guide.md 中针对具体操作的结果、错误情况和状态信息。
文档包含敏感的示例数据	发布前，将租户、用户、令牌和客户数据替换为中性的示例。
缺少弃用元数据	添加 x-sap-stateInfo 以及 references/deprecation-policy.md 中的迁移指南。

外部资源

标准

• OpenAPI Specification：https://spec.openapis.org/oas/latest.html
• OData v4.01：https://www.odata.org/documentation/
• Javadoc：https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html
• JSDoc 3：https://jsdoc.app/
• Doxygen：https://www.doxygen.nl/

SAP 资源

• SAP API Business Hub：https://api.sap.com/
• SAP Developer Center：https://developers.sap.com/
• SAP Help Portal：https://help.sap.com/
• SAP Community：https://community.sap.com/

来源

• SAP API Style Guide：https://github.com/SAP-docs/api-style-guide

更新与维护

源版本：SAP API Style Guide 2025.01（已根据提交 902247f 验证）

近期变更：

• 源代码库于 2025-10-28 更新
• 已核验并更新参考文件的行数
• 新增完整的目录，便于导航
• 新增捆绑资源部分，便于查找内容

更新此技能：

1. 检查源代码库是否有变更：https://github.com/SAP-docs/api-style-guide
2. 查看“What's New in the Style Guide”
3. 更新受影响的参考文件
4. 如果标准发生变化，请更新模板
5. 更新“Last Verified”日期

建议每季度审核：每 3 个月检查一次更新

下次审核：2026-02-27

---

技能版本：2.4.1 最后更新：2026-06-14 许可证：GPL-3.0 维护者：Eduard Jiglau | [email protected] | sap-ai-skills.com | https://github.com/secondsky/sap-skills