呱呱聚合
← 返回基因库
后端与接口

在编写或评审 SAP REST/OData/Java/Jav…

适用于需要按 SAP API Style Guide 创建、评审、发布或弃用 SAP API 文档与 OpenAPI/OData/原生库注释的团队。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 marc.cai 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 59/100 ×0.15

适用场景

在编写或评审 SAP REST/ODat特定

解决思路

  1. 先确定正在处理的是 REST、OData、Java、JavaScript、.NET 还是 C/C++ API。
  2. 若为 REST/OData 且文档自动生成，查阅 references/rest-odata-openapi-guide.md，应用 OpenAPI specification standards、package/API/operation descriptions、parameters/responses/components 以及 SAP API Business Hub requirements。
  3. 若为 REST/OData 且文档手写，查阅 references/manual-templates-guide.md，使用 REST 模板的 2-level 结构（overview → method）或 OData 模板的 3-level 结构（service → resource → operation），并使用 templates/ 中的即用文件。
  4. 若为 Native Library API，按语言查阅 references/java-javascript-dotnet-guide.md：Java、JavaScript、.NET、C/C++ 均应用 documentation comments structure、language-specific tags、classes/methods/enums templates 和完整代码示例。
  5. 处理命名任务时，查阅 references/naming-conventions.md，应用 REST/OData naming（resources、parameters、URIs）以及 native library naming（classes、methods、constants），并避免 common mistakes。
  6. 编写描述时，查阅 references/rest-odata-openapi-guide.md，编写 package descriptions、API details（info object）、operations、parameters、responses。
  7. 执行质量保证时，查阅 references/quality-processes.md，使用 Complete API Quality Checklist、review workflows、development team guidelines。
  8. 弃用 API 时，查阅 references/deprecation-policy.md，应用 lifecycle states（beta、active、deprecated、decommissioned）、timeline requirements（12+ months support）和 required metadata（x-sap-stateInfo）。
  9. 编写 Developer Guides 时，查阅 references/developer-guides.md，应用 structure guidelines、content selection、code sample standards。
  10. 确保所有 SAP API 文档遵循一致惯例：Naming 按语言使用 camelCase、PascalCase、kebab-case；Structure 分层并具有清晰导航；Formatting 句子首字母大写并以句号结尾；Language 使用 American English。
  11. 按 API 类型应用对应标准：REST 使用 OpenAPI 3.0.3 与 Swagger；OData 使用 v4.01、v3.0、v2.0；Java 使用 Javadoc 与 javadoc；JavaScript 使用 JSDoc 3 与 jsdoc；.NET 使用 XML Comments 与 DocFX；C/C++ 使用 Doxygen 与 doxygen。
  12. 按渐进披露组织文档：高层 overview 提供上下文和导航；详细 references 覆盖具体 API、methods、operations；examples 和 templates 展示实际用法。
  13. 满足质量标准：文档必须由 User Assistance (UA) 开发者审核；使用一致命名和术语；包含完整 parameter 和 response descriptions；示例中避免敏感数据；提供可运行代码示例；保持链接和交叉引用准确。
  14. 遵守字符限制：API Title 限制为 80，用于 info.title；API Short Text 限制为 180，用于 x-sap-shortText；Package Short Desc 限制为 250；Operation Summary 限制为 255；Description 限制为 1024。
  15. 应用 API 命名通用规则：名称中不要包含「API」；不要加「SAP」前缀；不要使用动词；正确大写单词；避免技术细节如 REST、OData。
  16. 修正命名反例：不要用「Custom Forms API」，改为「Custom Forms」；不要用「SAP Document Approval」，改为「Document Approval」；不要用「Configuring Portal」，改为「Portal Configuration」。
  17. 编写 Java/JavaScript 文档注释时使用 @param <name> <description>、@return <description>、@throws <class> <description>、@deprecated <description>。
  18. 编写 .NET 文档注释时使用 <summary>、<param name="">、<returns>、<exception cref="">。
  19. 管理 API 生命周期状态：Beta 为预生产测试且无保证，需 state: beta；Active 为生产就绪默认状态且完整支持，元数据可选；Deprecated 表示被后继替代，需 12+ months 支持，并需要 state、deprecationDate、successorApi；Decommissioned 表示完全退役且无支持，需记录移除。
  20. 加载大型参考前先搜索：使用 rg -n "<resource|operation|parameter|description|template|deprecation|x-sap-stateInfo>" references/*.md 定位确切规则，然后只打开相关摘录。
  21. 使用 references/manual-templates-guide.md 时，搜索 REST API Template、OData Operation Template、field requirements、method 或具体资源名。
  22. 使用 references/rest-odata-openapi-guide.md 时，查找 OpenAPI、OData、operation descriptions、responses、parameters、SAP API Business Hub publication checks。
  23. 使用 references/naming-conventions.md 时，查找 resource、operation、package、class、method、parameter、enum、constant naming。
  24. 使用 references/java-javascript-dotnet-guide.md 时，查找 Javadoc、JSDoc、XML doc comments、native SDK documentation tags。
  25. 使用 references/deprecation-policy.md 时，查找 lifecycle state、migration guidance、x-sap-stateInfo。
  26. 使用 references/quality-processes.md 时，查找 review checklists、gates、documentation quality workflows。
  27. 使用 templates/ 中的 REST API Templates（2-Level）：rest-api-overview-template.md 用于 resource-level overview，rest-api-method-template.md 用于 individual endpoint details。
  28. 使用 templates/ 中的 OData API Templates（3-Level）：odata-service-overview-template.md 用于 complete service overview，odata-resource-template.md 用于 individual resource/entity set，odata-operation-template.md 用于 specific operation details。
  29. 应用 templates 中的通用元素：Clear "How to Use" instructions、[Placeholder text] for customization、Complete section structure、Working examples、Inline guidance。
  30. 查阅 rest-odata-openapi-guide.md（约 2,800 lines）以获取 OpenAPI specification guidelines、Package/API/operation descriptions、Parameters/responses/components、Security schemes/tags/external docs、Character limits and anti-patterns。
  31. 查阅 manual-templates-guide.md（约 2,765 lines）以获取 REST API templates（2-level hierarchy）、OData API templates（3-level hierarchy）、Complete template structures、Field-by-field requirements、Best practices and examples。
  32. 查阅 naming-conventions.md（约 2,059 lines）以获取 REST/OData naming rules（resources、parameters、URIs）、Native library naming（classes、methods、constants、packages）、Language-specific conventions、Common mistakes with fixes、Decision trees and reference tables。
  33. 查阅 quality-processes.md（约 1,774 lines）以获取 Complete API Quality Checklist、Review workflows（developer + UA collaboration）、Development team guidelines、Common review findings and solutions、Process flowcharts。
  34. 查阅 java-javascript-dotnet-guide.md（约 1,517 lines）以获取 Documentation comments structure、Language-specific tags（Java、JavaScript、.NET、C/C++）、Templates for classes/methods/enums、Complete code examples、Best practices by language。
  35. 查阅 developer-guides.md（约 704 lines）以获取 Guide structure standards、Topic types（concept、reference、task）、Content selection criteria、Code sample standards（compilable、concise、commented）、Best practices。
  36. 查阅 deprecation-policy.md（约 664 lines）以获取 API lifecycle states（beta、active、deprecated、decommissioned）、Timeline requirements（12+ months support、24+ months lifespan）、Required metadata（x-sap-stateInfo、artifact.json）、Decommission process、Complete examples。
  37. 查阅 glossary-resources.md（约 472 lines）以获取 Complete terminology definitions（API、OData、OpenAPI 等）、External resource links（standards、tools、SAP resources）、Quick reference tables、Tool documentation links。
  38. 使用 Bundled Resources：references/ 包含 9 detailed reference files（总计约 10,861 lines），覆盖 SAP API Style Guide standards，并采用 progressive disclosure architecture。
  39. 执行 Step 1：Identify API Type，确定要文档化的是 REST、OData、Java、JavaScript、.NET 还是 C/C++ API。
  40. 执行 Step 2：Choose Approach。Auto-Generated 时在 source code 中写 documentation comments、使用适当 tags、提交审核；Manual 时从 templates/ 选择 template、定制 [placeholders]、遵循 hierarchy、用 checklist 验证。
  41. 执行 Step 3：Apply Standards。按任务查阅 naming-conventions.md、rest-odata-openapi-guide.md 或 java-javascript-dotnet-guide.md、quality-processes.md、deprecation-policy.md。
  42. 执行 Step 4：Quality Check。发布前对照 API Quality Checklist（quality-processes.md）检查；验证 naming conventions（naming-conventions.md）；检查 character limits；确认 examples 中无敏感数据；测试所有 code examples；验证 links 可用；获得 UA developer review。
  43. 执行 Step 5：Publish。REST/OData 提交到 SAP API Business Hub；Java/JavaScript/.NET 使用合适工具生成（Javadoc、JSDoc、DocFX）；Developer Guides 发布到 SAP Help Portal 或 product documentation。
  44. 避免命名陷阱：不要包含「API」；不要使用「SAP」前缀；不要使用动词。
  45. 避免描述陷阱：不要使用第二人称；不要使用泛泛响应如「No content」，应写「Product is out of stock」；不要在 description 中重复 summary。
  46. 避免文档陷阱：不要跳过 UA review；不要在 examples 中包含敏感数据；不要缺失 required tags；不要术语不一致。
  47. 修复常见问题：API names 使用 verbs 或冗余「API」suffixes 时，在写 descriptions 前应用 references/naming-conventions.md 的命名规则。
  48. 修复常见问题：OpenAPI descriptions 过于泛泛时，使用 operation-specific outcomes、error cases、state information，来源为 references/rest-odata-openapi-guide.md。
  49. 修复常见问题：文档包含敏感示例数据时，在发布前替换 tenant、user、token、customer 数据为中立示例。
  50. 修复常见问题：deprecation metadata 缺失时，从 references/deprecation-policy.md 添加 x-sap-stateInfo 和 migration guidance。
  51. 处理 OData service documentation、CAP API patterns、service definition standards 时，结合 sap-cap-capire 技能。
  52. 处理 API consumption patterns、Fiori app integration、OData best practices 时，结合 sap-fiori-tools 技能。
  53. 文档化 ABAP APIs、实现 REST services、遵循 API design patterns 时，结合 sap-abap 技能。
  54. 处理 frontend API integration、OData consumption、UI service patterns 时，结合 sapui5 技能。
  55. 处理 BTP service API documentation、integration patterns 时，结合 sap-btp-cloud-platform 技能。
  56. 需要标准依据时查阅 OpenAPI Specification：https://spec.openapis.org/oas/latest.html。
  57. 需要标准依据时查阅 OData v4.01：https://www.odata.org/documentation/。
  58. 需要标准依据时查阅 Javadoc：https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html。
  59. 需要标准依据时查阅 JSDoc 3：https://jsdoc.app/。
  60. 需要标准依据时查阅 Doxygen：https://www.doxygen.nl/。
  61. 需要 SAP 资源时查阅 SAP API Business Hub：https://api.sap.com/。
  62. 需要 SAP 资源时查阅 SAP Developer Center：https://developers.sap.com/。
  63. 需要 SAP 资源时查阅 SAP Help Portal：https://help.sap.com/。
  64. 需要 SAP 资源时查阅 SAP Community：https://community.sap.com/。
  65. 需要源文档时查阅 SAP API Style Guide：https://github.com/SAP-docs/api-style-guide。
  66. 维护该技能时，检查源仓库变化：https://github.com/SAP-docs/api-style-guide。
  67. 维护该技能时，查看「What's New in the Style Guide」。
  68. 维护该技能时，更新受影响的 reference files。
  69. 维护该技能时，如果 standards changed，则更新 templates。
  70. 维护该技能时，更新「Last Verified」日期。
  71. 维护该技能时，建议每 3 个月检查一次更新；Next Review 为 2026-02-27。

适用边界 · 注意事项