Back to Details

sap-api-style

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SAP API Style Guide

SAP API风格指南

Related Skills

相关技能

  • sap-cap-capire: Use for OData service documentation, CAP API patterns, and service definition standards
  • sap-fiori-tools: Use for API consumption patterns, Fiori app integration, and OData best practices
  • sap-abap: Use when documenting ABAP APIs, implementing REST services, or following API design patterns
  • sapui5: Use for frontend API integration, OData consumption, and UI service patterns
  • sap-btp-cloud-platform: Use for BTP service API documentation and integration patterns
  • 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文档和集成模式

Table of Contents

目录

  1. Overview
  2. When to Use This Skill
  3. Quick Decision Tree
  4. Core Principles
  5. Quick Reference Tables
  6. Templates Available
  7. Reference Files
  8. Instructions for Use
  9. Common Pitfalls to Avoid
  10. External Resources
  11. Updates and Maintenance
  1. 概述
  2. 适用场景
  3. 快速决策树
  4. 核心原则
  5. 快速参考表
  6. 可用模板
  7. 参考文件
  8. 使用说明
  9. 常见误区
  10. 外部资源
  11. 更新与维护

Overview

概述

This skill provides comprehensive guidance for documenting SAP APIs according to official SAP API Style Guide standards. It covers all major API types and documentation approaches used across the SAP ecosystem.
Documentation Source: https://github.com/SAP-docs/api-style-guide (76 files extracted)
Last Verified: 2025-11-21
本技能为遵循官方SAP API风格指南标准编写SAP API文档提供全面指导，涵盖SAP生态系统中所有主要API类型和文档编写方法。
文档来源：https://github.com/SAP-docs/api-style-guide（提取自76个文件）
最后验证日期：2025-11-21

When to Use This Skill

适用场景

Use this skill when:
  • Creating API documentation for REST, OData, Java, JavaScript, .NET, or C/C++ APIs
  • Writing OpenAPI specifications for SAP API Business Hub
  • Reviewing API names for SAP naming convention compliance
  • Documenting API parameters, responses, operations with proper formatting
  • Creating manual API documentation using SAP templates
  • Writing documentation comments in source code (Javadoc, JSDoc, XML comments)
  • Implementing API deprecation following SAP lifecycle policies
  • Developing developer guides or service documentation
  • Performing quality checks on API documentation
  • Publishing APIs to SAP API Business Hub
在以下场景中使用本技能：
  • 创建API文档：REST、OData、Java、JavaScript、.NET或C/C++ API
  • 编写OpenAPI规范：用于SAP API Business Hub
  • 评审API命名：确保符合SAP命名规范
  • 编写API参数、响应、操作文档：使用正确格式
  • 创建手动API文档：使用SAP模板
  • 编写源代码文档注释：Javadoc、JSDoc、XML注释
  • 实施API弃用：遵循SAP生命周期策略
  • 编写开发者指南或服务文档
  • API文档质量检查
  • 发布API到SAP API Business Hub

Quick Decision Tree

快速决策树

What Type of API?

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
REST/OData API
├─ 自动生成（OpenAPI/Swagger）？
│  └─ references/rest-odata-openapi-guide.md
│     • OpenAPI规范标准
│     • 包、API、操作描述
│     • 参数、响应、组件
│     • SAP API Business Hub要求
│
└─ 手动编写？
   └─ references/manual-templates-guide.md
      • REST模板（两级：概览 → 方法）
      • OData模板（三级：服务 → 资源 → 操作）
      • 完整字段要求
      • templates/目录下的即用型文件

原生库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
    • 文档注释结构
    • 语言特定标签
    • 类、方法、枚举模板
    • 完整代码示例

What Task?

任务类型？

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
命名
└─ references/naming-conventions.md
   • REST/OData命名（资源、参数、URI）
   • 原生库命名（类、方法、常量）
   • 常见错误及规避方法

编写描述
└─ references/rest-odata-openapi-guide.md
   • 包描述
   • API详情（info对象）
   • 操作、参数、响应

质量保证
└─ references/quality-processes.md
   • 完整API质量检查清单
   • 评审工作流
   • 开发团队指南

API弃用
└─ references/deprecation-policy.md
   • 生命周期状态（beta、活跃、已弃用、已停用）
   • 时间线要求（12个月以上支持）
   • 必填元数据（x-sap-stateInfo）

开发者指南
└─ references/developer-guides.md
   • 结构指南
   • 内容选择
   • 代码示例标准

Core Principles

核心原则

1. Consistency Across SAP APIs

1. SAP API一致性

All SAP API documentation follows consistent conventions:
  • Naming: Language-specific (camelCase, PascalCase, kebab-case)
  • Structure: Hierarchical with clear navigation
  • Formatting: Sentences start with capitals, end with periods
  • Language: American English
所有SAP API文档遵循统一规范：
  • 命名：语言特定格式（camelCase、PascalCase、kebab-case）
  • 结构：分层结构，导航清晰
  • 格式：句子首字母大写，句末加句号
  • 语言：美式英语

2. API-Type-Specific Standards

2. API类型特定标准

API TypeStandardToolDocumentation
RESTOpenAPI 3.0.3SwaggerSpec
ODatav4.01, v3.0, v2.0VariousOData.org
JavaJavadocjavadocOracle
JavaScriptJSDoc 3jsdocJSDoc.app
.NETXML CommentsDocFXMicrosoft
C/C++DoxygendoxygenDoxygen.nl
API类型标准工具文档参考
RESTOpenAPI 3.0.3Swagger规范
ODatav4.01, v3.0, v2.0多种工具OData.org
JavaJavadocjavadocOracle
JavaScriptJSDoc 3jsdocJSDoc.app
.NETXML注释DocFXMicrosoft
C/C++DoxygendoxygenDoxygen.nl

3. Progressive Disclosure

3. 渐进式披露

Documentation organized hierarchically:
  • High-level overviews provide context and navigation
  • Detailed references cover specific APIs, methods, operations
  • Examples and templates demonstrate practical usage
文档采用分层组织：
  • 高层概览：提供上下文和导航
  • 详细参考：覆盖特定API、方法、操作
  • 示例与模板：演示实际用法

4. Quality Standards

4. 质量标准

All documentation must:
  • ✅ Be reviewed by User Assistance (UA) developers
  • ✅ Use consistent naming and terminology
  • ✅ Include complete parameter and response descriptions
  • ✅ Avoid sensitive data in examples
  • ✅ Provide working code examples
  • ✅ Maintain accurate links and cross-references
所有文档必须满足：
  • ✅ 经过用户辅助（UA）开发者评审
  • ✅ 使用一致的命名和术语
  • ✅ 包含完整的参数和响应描述
  • ✅ 示例中不包含敏感数据
  • ✅ 提供可运行的代码示例
  • ✅ 维护准确的链接和交叉引用

Quick Reference Tables

快速参考表

Character Limits

字符限制

ElementLimitUse Case
API Title80
info.title
in OpenAPI
API Short Text180
x-sap-shortText
Package Short Desc250Package tile description
Operation Summary255Operation summary line
Description1024General descriptions
元素限制使用场景
API标题80OpenAPI中的
info.title
API短文本180
x-sap-shortText
包简短描述250包卡片描述
操作摘要255操作摘要行
描述1024通用描述

API Naming Rules

API命名规则

General Rules (all API types):
  • ❌ Don't include "API" in name: "Custom Forms API" → ✅ "Custom Forms"
  • ❌ Don't include "SAP" prefix: "SAP Document Approval" → ✅ "Document Approval"
  • ❌ Don't use verbs: "Configuring Portal" → ✅ "Portal Configuration"
  • ✅ Capitalize words properly
  • ✅ Avoid technical specifics (REST, OData, etc.)
See 
references/naming-conventions.md
for complete language-specific rules.
通用规则（所有API类型）：
  • ❌ 名称中不包含"API"："Custom Forms API" → ✅ "Custom Forms"
  • ❌ 不使用"SAP"前缀："SAP Document Approval" → ✅ "Document Approval"
  • ❌ 不使用动词："Configuring Portal" → ✅ "Portal Configuration"
  • ✅ 单词正确大写
  • ✅ 避免技术细节（REST、OData等）
完整语言特定规则请参考
references/naming-conventions.md
。

Common Documentation Tags

常见文档标签

Java/JavaScript:
  • @param <name> <description>
    - Parameter documentation
  • @return <description>
    - Return value
  • @throws <class> <description>
    - Exception
  • @deprecated <description>
    - Deprecation notice
.NET:
  • <summary>
    - Brief description
  • <param name="">
    - Parameter
  • <returns>
    - Return value
  • <exception cref="">
    - Exception
See 
references/java-javascript-dotnet-guide.md
for complete tag reference.
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 Lifecycle States

API生命周期状态

StateDefinitionSupportMetadata Required
BetaPre-production testingNo guarantees
state: beta
ActiveProduction-ready (default)Full supportOptional
DeprecatedReplaced by successor12+ months
state
, 
deprecationDate
, 
successorApi
DecommissionedFully retiredNoneDocument removal
See 
references/deprecation-policy.md
for complete timeline and process requirements.
状态定义支持服务必填元数据
Beta预生产测试无保障
state: beta
活跃可用于生产环境（默认）全面支持可选
已弃用被替代API取代12个月以上支持
state
、
deprecationDate
、
successorApi
已停用完全下线无支持文档移除
完整时间线和流程要求请参考
references/deprecation-policy.md
。

Templates Available

可用模板

Ready-to-use templates in 
templates/
directory:
templates/
目录下的即用型模板：

REST API Templates (2-Level)

REST API模板（两级）

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

OData API Templates (3-Level)

OData API模板（三级）

  1. odata-service-overview-template.md - Complete service overview
  2. odata-resource-template.md - Individual resource/entity set
  3. odata-operation-template.md - Specific operation details
All templates include:
  • Clear "How to Use" instructions
  • [Placeholder text] for customization
  • Complete section structure
  • Working examples
  • Inline guidance
  1. odata-service-overview-template.md - 完整服务概览
  2. odata-resource-template.md - 单个资源/实体集
  3. odata-operation-template.md - 特定操作详情
所有模板包含：
  • 清晰的“使用方法”说明
  • 用于自定义的[占位文本]
  • 完整的章节结构
  • 可运行示例
  • 内联指导

Reference Files

参考文件

Complete Guides Available

可用完整指南

  1. rest-odata-openapi-guide.md (2,800 lines)
    • Complete OpenAPI specification guidelines
    • Package, API, operation descriptions
    • Parameters, responses, components
    • Security schemes, tags, external docs
    • Character limits and anti-patterns
  2. 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
  3. 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
  4. 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
  5. 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
  6. developer-guides.md (704 lines)
    • Guide structure standards
    • Topic types (concept, reference, task)
    • Content selection criteria
    • Code sample standards (compilable, concise, commented)
    • Best practices
  7. 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
  8. glossary-resources.md (472 lines)
    • Complete terminology definitions (API, OData, OpenAPI, etc.)
    • External resource links (standards, tools, SAP resources)
    • Quick reference tables
    • Tool documentation links
    • Content extraction and organization tracking
    • Source file mapping from SAP documentation
    • Consolidation and adaptation notes
  1. rest-odata-openapi-guide.md（2800行）
    • 完整OpenAPI规范指南
    • 包、API、操作描述
    • 参数、响应、组件
    • 安全方案、标签、外部文档
    • 字符限制与反模式
  2. manual-templates-guide.md（2765行）
    • REST API模板（两级结构）
    • OData API模板（三级结构）
    • 完整模板结构
    • 逐字段要求
    • 最佳实践与示例
  3. naming-conventions.md（2059行）
    • REST/OData命名规则（资源、参数、URI）
    • 原生库命名（类、方法、常量、包）
    • 语言特定规范
    • 常见错误及修复方案
    • 决策树与参考表
  4. quality-processes.md（1774行）
    • 完整API质量检查清单
    • 评审工作流（开发者+UA协作）
    • 开发团队指南
    • 常见评审问题与解决方案
    • 流程流程图
  5. java-javascript-dotnet-guide.md（1517行）
    • 文档注释结构
    • 语言特定标签（Java、JavaScript、.NET、C/C++）
    • 类、方法、枚举模板
    • 完整代码示例
    • 各语言最佳实践
  6. developer-guides.md（704行）
    • 指南结构标准
    • 主题类型（概念、参考、任务）
    • 内容选择标准
    • 代码示例标准（可编译、简洁、带注释）
    • 最佳实践
  7. deprecation-policy.md（664行）
    • API生命周期状态（beta、活跃、已弃用、已停用）
    • 时间线要求（12个月以上支持，24个月以上生命周期）
    • 必填元数据（x-sap-stateInfo、artifact.json）
    • 停用流程
    • 完整示例
  8. glossary-resources.md（472行）
    • 完整术语定义（API、OData、OpenAPI等）
    • 外部资源链接（标准、工具、SAP资源）
    • 快速参考表
    • 工具文档链接
    • 内容提取与组织跟踪
    • SAP文档源文件映射
    • 整合与适配说明

Bundled Resources

捆绑资源

This skill includes comprehensive documentation and templates organized for optimal use:
本技能包含组织优化的全面文档和模板：

Reference Guides (
references/
)

参考指南（
references/
）

  • 9 detailed reference files (10,861 total lines)
  • Complete coverage of SAP API Style Guide standards
  • Progressive disclosure architecture for efficient loading
  • 9份详细参考文件（共10861行）
  • 完整覆盖SAP API风格指南标准
  • 渐进式披露架构，加载高效

Template Files (
templates/
)

模板文件（
templates/
）

  1. rest-api-overview-template.md (217 lines) - Level 1 REST overview
  2. rest-api-method-template.md (477 lines) - Level 2 REST method details
  3. odata-service-overview-template.md (411 lines) - Level 1 OData service
  4. odata-resource-template.md (557 lines) - Level 2 OData resource
  5. odata-operation-template.md (681 lines) - Level 3 OData operation
Total: 2,343 lines of ready-to-use templates
  1. rest-api-overview-template.md（217行）- 一级REST概览
  2. rest-api-method-template.md（477行）- 二级REST方法详情
  3. odata-service-overview-template.md（411行）- 一级OData服务
  4. odata-resource-template.md（557行）- 二级OData资源
  5. odata-operation-template.md（681行）- 三级OData操作
总计：2343行即用型模板

Instructions for Use

使用说明

Step 1: Identify API Type

步骤1：确定API类型

Determine if you're documenting REST, OData, Java, JavaScript, .NET, or C/C++ API.
明确要编写文档的API类型：REST、OData、Java、JavaScript、.NET或C/C++。

Step 2: Choose Approach

步骤2：选择编写方式

Auto-Generated: Write documentation comments in source code → Use appropriate tags → Submit for review
Manual: Select template from 
templates/
→ Customize [placeholders] → Follow hierarchy → Validate with checklist
自动生成：在源代码中编写文档注释 → 使用对应标签 → 提交评审
手动编写：从
templates/
选择模板 → 自定义[占位符] → 遵循分层结构 → 使用检查清单验证

Step 3: Apply Standards

步骤3：应用标准

Consult appropriate reference file:
  • Naming: 
    naming-conventions.md
  • Descriptions: 
    rest-odata-openapi-guide.md
    or 
    java-javascript-dotnet-guide.md
  • Quality: 
    quality-processes.md
  • Deprecation: 
    deprecation-policy.md
参考对应文件：
  • 命名：
    naming-conventions.md
  • 描述编写：
    rest-odata-openapi-guide.md
    或
    java-javascript-dotnet-guide.md
  • 质量：
    quality-processes.md
  • 弃用：
    deprecation-policy.md

Step 4: Quality Check

步骤4：质量检查

Before publishing:
  1. Review against API Quality Checklist (
    quality-processes.md
    )
  2. Verify naming conventions (
    naming-conventions.md
    )
  3. Check character limits (see Quick Reference Tables above)
  4. Validate no sensitive data in examples
  5. Test all code examples
  6. Verify links work
  7. Obtain UA developer review
发布前需完成：
  1. 对照API质量检查清单（
    quality-processes.md
    ）评审
  2. 验证命名规范（
    naming-conventions.md
    ）
  3. 检查字符限制（见上方快速参考表）
  4. 确认示例中无敏感数据
  5. 测试所有代码示例
  6. 验证链接可用
  7. 获得UA开发者评审

Step 5: Publish

步骤5：发布

  • REST/OData: Submit to SAP API Business Hub
  • Java/JavaScript/.NET: Generate with appropriate tool (Javadoc, JSDoc, DocFX)
  • Developer Guides: Publish to SAP Help Portal or product documentation
  • REST/OData：提交到SAP API Business Hub
  • Java/JavaScript/.NET：使用对应工具生成（Javadoc、JSDoc、DocFX）
  • 开发者指南：发布到SAP帮助门户或产品文档

Common Pitfalls to Avoid

常见误区

Naming:
  • ❌ Including "API": "Custom Forms APIs" → ✅ "Custom Forms"
  • ❌ Using "SAP" prefix: "SAP Document Approval" → ✅ "Document Approval"
  • ❌ Using verbs: "Configuring Portal" → ✅ "Portal Configuration"
Descriptions:
  • ❌ Second person: "This operation creates..." → ✅ "Creates a new user"
  • ❌ Generic responses: "No content" → ✅ "Product is out of stock"
  • ❌ Repeating summary in description
Documentation:
  • ❌ Skipping UA review
  • ❌ Including sensitive data in examples
  • ❌ Missing required tags
  • ❌ Inconsistent terminology
See individual reference files for complete anti-patterns and fixes.
命名：
  • ❌ 包含"API"："Custom Forms APIs" → ✅ "Custom Forms"
  • ❌ 使用"SAP"前缀："SAP Document Approval" → ✅ "Document Approval"
  • ❌ 使用动词："Configuring Portal" → ✅ "Portal Configuration"
描述：
  • ❌ 使用第二人称："This operation creates..." → ✅ "创建新用户"
  • ❌ 通用响应描述："No content" → ✅ "产品缺货"
  • ❌ 描述重复摘要内容
文档编写：
  • ❌ 跳过UA评审
  • ❌ 示例中包含敏感数据
  • ❌ 缺失必填标签
  • ❌ 术语不一致
完整反模式与修复方案请见各参考文件。

External Resources

外部资源

Standards

标准

SAP Resources

SAP资源

Source

来源

Updates and Maintenance

更新与维护

Source Version: SAP API Style Guide 2025.01 (verified against commit 902247f)
Recent Changes:
  • Source repository updated 2025-10-28
  • Reference file line counts verified and updated
  • Added comprehensive Table of Contents for navigation
  • Added Bundled Resources section for content discovery
To Update This Skill:
  1. Check source repository for changes: https://github.com/SAP-docs/api-style-guide
  2. Review "What's New in the Style Guide"
  3. Update affected reference files
  4. Update templates if standards changed
  5. Update "Last Verified" date
Quarterly Review Recommended: Check for updates every 3 months
Next Review: 2026-02-27
Skill Version: 1.1.0 Last Updated: 2025-11-27 License: GPL-3.0 Maintainer: SAP Skills Team | https://github.com/secondsky/sap-skills
源版本：SAP API风格指南2025.01（基于提交902247f验证）
近期变更：
  • 源仓库更新于2025-10-28
  • 验证并更新了参考文件行数
  • 添加了全面的目录导航
  • 添加了捆绑资源章节，便于内容查找
技能更新步骤：
  1. 检查源仓库变更：https://github.com/SAP-docs/api-style-guide
  2. 查看“风格指南新增内容”
  3. 更新受影响的参考文件
  4. 若标准变更，更新模板
  5. 更新“最后验证”日期
建议季度评审：每3个月检查更新
下次评审日期：2026-02-27
技能版本：1.1.0 最后更新日期：2025-11-27 许可证：GPL-3.0 维护者：SAP Skills Team | https://github.com/secondsky/sap-skills