SAP API Style Guide
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
Table of Contents
- Overview
- When to Use This Skill
- Quick Decision Tree
- Core Principles
- Quick Reference Tables
- Templates Available
- Reference Files
- Instructions for Use
- Common Pitfalls to Avoid
- External Resources
- Updates and Maintenance
- Common Issues
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)
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
Quick Decision Tree
What Type of 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
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
Core Principles
1. Consistency Across SAP APIs
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
2. API-Type-Specific Standards
| API Type |
Standard |
Tool |
Documentation |
| REST |
OpenAPI 3.0.3 |
Swagger |
Spec |
| OData |
v4.01, v3.0, v2.0 |
Various |
OData.org |
| Java |
Javadoc |
javadoc |
Oracle |
| JavaScript |
JSDoc 3 |
jsdoc |
JSDoc.app |
| .NET |
XML Comments |
DocFX |
Microsoft |
| C/C++ |
Doxygen |
doxygen |
Doxygen.nl |
3. Progressive Disclosure
Documentation organized hierarchically:
- High-level overviews provide context and navigation
- Detailed references cover specific APIs, methods, operations
- Examples and templates demonstrate practical usage
4. Quality Standards
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
Quick Reference Tables
Character Limits
| Element |
Limit |
Use Case |
| API Title |
80 |
info.title in OpenAPI |
| API Short Text |
180 |
x-sap-shortText |
| Package Short Desc |
250 |
Package tile description |
| Operation Summary |
255 |
Operation summary line |
| Description |
1024 |
General descriptions |
API Naming Rules
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.
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.
API Lifecycle States
| State |
Definition |
Support |
Metadata Required |
| Beta |
Pre-production testing |
No guarantees |
state: beta |
| Active |
Production-ready (default) |
Full support |
Optional |
| Deprecated |
Replaced by successor |
12+ months |
state, deprecationDate, successorApi |
| Decommissioned |
Fully retired |
None |
Document removal |
See references/deprecation-policy.md for complete timeline and process requirements.
Large Reference Search Routing
Search large references before loading them. Use rg -n "<resource|operation|parameter|description|template|deprecation|x-sap-stateInfo>" references/*.md to locate the exact rule, then open only the relevant excerpt.
- Use
references/manual-templates-guide.md for manually written REST/OData documentation templates. Search for REST API Template, OData Operation Template, field requirements, method, or the resource name.
- Use
references/rest-odata-openapi-guide.md for OpenAPI, OData, operation descriptions, responses, parameters, and SAP API Business Hub publication checks.
- Use
references/naming-conventions.md for resource, operation, package, class, method, parameter, enum, and constant naming.
- Use
references/java-javascript-dotnet-guide.md for Javadoc, JSDoc, XML doc comments, and native SDK documentation tags.
- Use
references/deprecation-policy.md for lifecycle state, migration guidance, and x-sap-stateInfo.
- Use
references/quality-processes.md for review checklists, gates, and documentation quality workflows.
Templates Available
Ready-to-use templates in templates/ directory:
REST API Templates (2-Level)
- rest-api-overview-template.md - Resource-level overview
- rest-api-method-template.md - Individual endpoint details
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
All templates include:
- Clear "How to Use" instructions
- [Placeholder text] for customization
- Complete section structure
- Working examples
- Inline guidance
Reference Files
Complete Guides Available
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
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
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
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
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
developer-guides.md (704 lines)
- Guide structure standards
- Topic types (concept, reference, task)
- Content selection criteria
- Code sample standards (compilable, concise, commented)
- Best practices
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
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
Bundled Resources
This skill includes comprehensive documentation and templates organized for optimal use:
Reference Guides (references/)
- 9 detailed reference files (10,861 total lines)
- Complete coverage of SAP API Style Guide standards
- Progressive disclosure architecture for efficient loading
Template Files (templates/)
- rest-api-overview-template.md (217 lines) - Level 1 REST overview
- rest-api-method-template.md (477 lines) - Level 2 REST method details
- odata-service-overview-template.md (411 lines) - Level 1 OData service
- odata-resource-template.md (557 lines) - Level 2 OData resource
- odata-operation-template.md (681 lines) - Level 3 OData operation
Total: 2,343 lines of ready-to-use templates
Instructions for Use
Step 1: Identify API Type
Determine if you're documenting REST, OData, Java, JavaScript, .NET, or C/C++ API.
Step 2: Choose Approach
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
Step 3: Apply Standards
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
Step 4: Quality Check
Before publishing:
- Review against API Quality Checklist (
quality-processes.md)
- Verify naming conventions (
naming-conventions.md)
- Check character limits (see Quick Reference Tables above)
- Validate no sensitive data in examples
- Test all code examples
- Verify links work
- Obtain UA developer review
Step 5: Publish
- 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
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.
Common Issues
| Issue |
Correction |
| API names use verbs or redundant "API" suffixes |
Apply the naming rules in references/naming-conventions.md before writing descriptions. |
| OpenAPI descriptions are too generic |
Use operation-specific outcomes, error cases, and state information from references/rest-odata-openapi-guide.md. |
| Documentation contains sensitive sample data |
Replace tenant, user, token, and customer data with neutral examples before publishing. |
| Deprecation metadata is missing |
Add x-sap-stateInfo and migration guidance from references/deprecation-policy.md. |
External Resources
Standards
SAP Resources
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:
- Check source repository for changes: https://github.com/SAP-docs/api-style-guide
- Review "What's New in the Style Guide"
- Update affected reference files
- Update templates if standards changed
- Update "Last Verified" date
Quarterly Review Recommended: Check for updates every 3 months
Next Review: 2026-02-27
Skill Version: 2.4.1
Last Updated: 2026-06-14
License: GPL-3.0
Maintainer: Eduard Jiglau | hello@sap-ai-skills.com | sap-ai-skills.com | https://github.com/secondsky/sap-skills
1---
2name: sap-api-style
3description: |
4 This skill provides comprehensive guidance for documenting SAP APIs following the SAP API Style Guide standards.
5 It should be used when creating or reviewing API documentation for REST, OData, Java, JavaScript, .NET, or C/C++ APIs.
6
7 The skill covers naming conventions, documentation comments, OpenAPI specifications, quality checklists, deprecation policies,
8 and manual documentation templates. It ensures consistency with SAP API Business Hub standards and industry best practices.
9
10 Keywords: SAP API, REST, OData, OpenAPI, Swagger, Javadoc, JSDoc, XML documentation, API Business Hub, API naming,
11 API deprecation, x-sap-stateInfo, Entity Data Model, EDM, documentation tags, API quality, API templates
12license: GPL-3.0
13metadata:
14 source: https://skillmd.com/skills/secondsky/sap-api-style
15 maintainer: "Eduard Jiglau"
16 maintainer_email: "hello@sap-ai-skills.com"
17 website: "https://sap-ai-skills.com"
18 version: "2.4.1"
19 last_verified: "2026-02-25"
20 source_version: "2025.01"
21 source_commit: "902247f3afb6a0cb3fa110b284bb5d93a65c1268"
22 source_license: "CC-BY-4.0"
23---
24
25# SAP API Style Guide
26
27## Related Skills
28
29- **sap-cap-capire**: Use for OData service documentation, CAP API patterns, and service definition standards
30- **sap-fiori-tools**: Use for API consumption patterns, Fiori app integration, and OData best practices
31- **sap-abap**: Use when documenting ABAP APIs, implementing REST services, or following API design patterns
32- **sapui5**: Use for frontend API integration, OData consumption, and UI service patterns
33- **sap-btp-cloud-platform**: Use for BTP service API documentation and integration patterns
34
35## Table of Contents
36
371. [Overview](#overview)
382. [When to Use This Skill](#when-to-use-this-skill)
393. [Quick Decision Tree](#quick-decision-tree)
404. [Core Principles](#core-principles)
415. [Quick Reference Tables](#quick-reference-tables)
426. [Templates Available](#templates-available)
437. [Reference Files](#reference-files)
448. [Instructions for Use](#instructions-for-use)
459. [Common Pitfalls to Avoid](#common-pitfalls-to-avoid)
4610. [External Resources](#external-resources)
4711. [Updates and Maintenance](#updates-and-maintenance)
4812. [Common Issues](#common-issues)
49
50## Overview
51
52This 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.
53
54**Documentation Source**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide) (76 files extracted)
55
56## When to Use This Skill
57
58Use this skill when:
59
60- **Creating API documentation** for REST, OData, Java, JavaScript, .NET, or C/C++ APIs
61- **Writing OpenAPI specifications** for SAP API Business Hub
62- **Reviewing API names** for SAP naming convention compliance
63- **Documenting API parameters, responses, operations** with proper formatting
64- **Creating manual API documentation** using SAP templates
65- **Writing documentation comments** in source code (Javadoc, JSDoc, XML comments)
66- **Implementing API deprecation** following SAP lifecycle policies
67- **Developing developer guides** or service documentation
68- **Performing quality checks** on API documentation
69- **Publishing APIs** to SAP API Business Hub
70
71## Quick Decision Tree
72
73### What Type of API?
74
75```
76REST/OData API
77├─ Auto-generated (OpenAPI/Swagger)?
78│ └─ references/rest-odata-openapi-guide.md
79│ • OpenAPI specification standards
80│ • Package, API, operation descriptions
81│ • Parameters, responses, components
82│ • SAP API Business Hub requirements
83│
84└─ Manually written?
85 └─ references/manual-templates-guide.md
86 • REST templates (2-level: overview → method)
87 • OData templates (3-level: service → resource → operation)
88 • Complete field requirements
89 • templates/ directory for ready-to-use files
90
91Native Library API
92├─ Java → references/java-javascript-dotnet-guide.md
93├─ JavaScript → references/java-javascript-dotnet-guide.md
94├─ .NET (C#) → references/java-javascript-dotnet-guide.md
95└─ C/C++ → references/java-javascript-dotnet-guide.md
96 • Documentation comments structure
97 • Language-specific tags
98 • Templates for classes, methods, enums
99 • Complete code examples
100```
101
102### What Task?
103
104```
105Naming
106└─ references/naming-conventions.md
107 • REST/OData naming (resources, parameters, URIs)
108 • Native library naming (classes, methods, constants)
109 • Common mistakes to avoid
110
111Writing Descriptions
112└─ references/rest-odata-openapi-guide.md
113 • Package descriptions
114 • API details (info object)
115 • Operations, parameters, responses
116
117Quality Assurance
118└─ references/quality-processes.md
119 • Complete API Quality Checklist
120 • Review workflows
121 • Development team guidelines
122
123Deprecating APIs
124└─ references/deprecation-policy.md
125 • Lifecycle states (beta, active, deprecated, decommissioned)
126 • Timeline requirements (12+ months support)
127 • Required metadata (x-sap-stateInfo)
128
129Developer Guides
130└─ references/developer-guides.md
131 • Structure guidelines
132 • Content selection
133 • Code sample standards
134```
135
136## Core Principles
137
138### 1. Consistency Across SAP APIs
139
140All SAP API documentation follows consistent conventions:
141- **Naming**: Language-specific (camelCase, PascalCase, kebab-case)
142- **Structure**: Hierarchical with clear navigation
143- **Formatting**: Sentences start with capitals, end with periods
144- **Language**: American English
145
146### 2. API-Type-Specific Standards
147
148| API Type | Standard | Tool | Documentation |
149|----------|----------|------|---------------|
150| REST | OpenAPI 3.0.3 | Swagger | [Spec](https://spec.openapis.org/) |
151| OData | v4.01, v3.0, v2.0 | Various | [OData.org](https://www.odata.org/) |
152| Java | Javadoc | javadoc | [Oracle](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html) |
153| JavaScript | JSDoc 3 | jsdoc | [JSDoc.app](https://jsdoc.app/) |
154| .NET | XML Comments | DocFX | [Microsoft](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) |
155| C/C++ | Doxygen | doxygen | [Doxygen.nl](https://www.doxygen.nl/) |
156
157### 3. Progressive Disclosure
158
159Documentation organized hierarchically:
160- **High-level overviews** provide context and navigation
161- **Detailed references** cover specific APIs, methods, operations
162- **Examples and templates** demonstrate practical usage
163
164### 4. Quality Standards
165
166All documentation must:
167- ✅ Be reviewed by User Assistance (UA) developers
168- ✅ Use consistent naming and terminology
169- ✅ Include complete parameter and response descriptions
170- ✅ Avoid sensitive data in examples
171- ✅ Provide working code examples
172- ✅ Maintain accurate links and cross-references
173
174## Quick Reference Tables
175
176### Character Limits
177
178| Element | Limit | Use Case |
179|---------|-------|----------|
180| API Title | 80 | `info.title` in OpenAPI |
181| API Short Text | 180 | `x-sap-shortText` |
182| Package Short Desc | 250 | Package tile description |
183| Operation Summary | 255 | Operation summary line |
184| Description | 1024 | General descriptions |
185
186### API Naming Rules
187
188**General Rules** (all API types):
189- ❌ Don't include "API" in name: ~~"Custom Forms API"~~ → ✅ "Custom Forms"
190- ❌ Don't include "SAP" prefix: ~~"SAP Document Approval"~~ → ✅ "Document Approval"
191- ❌ Don't use verbs: ~~"Configuring Portal"~~ → ✅ "Portal Configuration"
192- ✅ Capitalize words properly
193- ✅ Avoid technical specifics (REST, OData, etc.)
194
195See `references/naming-conventions.md` for complete language-specific rules.
196
197### Common Documentation Tags
198
199**Java/JavaScript**:
200- `@param <name> <description>` - Parameter documentation
201- `@return <description>` - Return value
202- `@throws <class> <description>` - Exception
203- `@deprecated <description>` - Deprecation notice
204
205**.NET**:
206- `<summary>` - Brief description
207- `<param name="">` - Parameter
208- `<returns>` - Return value
209- `<exception cref="">` - Exception
210
211See `references/java-javascript-dotnet-guide.md` for complete tag reference.
212
213### API Lifecycle States
214
215| State | Definition | Support | Metadata Required |
216|-------|-----------|---------|-------------------|
217| **Beta** | Pre-production testing | No guarantees | `state: beta` |
218| **Active** | Production-ready (default) | Full support | Optional |
219| **Deprecated** | Replaced by successor | 12+ months | `state`, `deprecationDate`, `successorApi` |
220| **Decommissioned** | Fully retired | None | Document removal |
221
222See `references/deprecation-policy.md` for complete timeline and process requirements.
223
224## Large Reference Search Routing
225
226Search large references before loading them. Use `rg -n "<resource|operation|parameter|description|template|deprecation|x-sap-stateInfo>" references/*.md` to locate the exact rule, then open only the relevant excerpt.
227
228- Use `references/manual-templates-guide.md` for manually written REST/OData documentation templates. Search for `REST API Template`, `OData Operation Template`, `field requirements`, `method`, or the resource name.
229- Use `references/rest-odata-openapi-guide.md` for OpenAPI, OData, operation descriptions, responses, parameters, and SAP API Business Hub publication checks.
230- Use `references/naming-conventions.md` for resource, operation, package, class, method, parameter, enum, and constant naming.
231- Use `references/java-javascript-dotnet-guide.md` for Javadoc, JSDoc, XML doc comments, and native SDK documentation tags.
232- Use `references/deprecation-policy.md` for lifecycle state, migration guidance, and `x-sap-stateInfo`.
233- Use `references/quality-processes.md` for review checklists, gates, and documentation quality workflows.
234
235## Templates Available
236
237Ready-to-use templates in `templates/` directory:
238
239### REST API Templates (2-Level)
2401. **rest-api-overview-template.md** - Resource-level overview
2412. **rest-api-method-template.md** - Individual endpoint details
242
243### OData API Templates (3-Level)
2441. **odata-service-overview-template.md** - Complete service overview
2452. **odata-resource-template.md** - Individual resource/entity set
2463. **odata-operation-template.md** - Specific operation details
247
248All templates include:
249- Clear "How to Use" instructions
250- [Placeholder text] for customization
251- Complete section structure
252- Working examples
253- Inline guidance
254
255## Reference Files
256
257### Complete Guides Available
258
2591. **rest-odata-openapi-guide.md** (2,800 lines)
260 - Complete OpenAPI specification guidelines
261 - Package, API, operation descriptions
262 - Parameters, responses, components
263 - Security schemes, tags, external docs
264 - Character limits and anti-patterns
265
2662. **manual-templates-guide.md** (2,765 lines)
267 - REST API templates (2-level hierarchy)
268 - OData API templates (3-level hierarchy)
269 - Complete template structures
270 - Field-by-field requirements
271 - Best practices and examples
272
2733. **naming-conventions.md** (2,059 lines)
274 - REST/OData naming rules (resources, parameters, URIs)
275 - Native library naming (classes, methods, constants, packages)
276 - Language-specific conventions
277 - Common mistakes with fixes
278 - Decision trees and reference tables
279
2804. **quality-processes.md** (1,774 lines)
281 - Complete API Quality Checklist
282 - Review workflows (developer + UA collaboration)
283 - Development team guidelines
284 - Common review findings and solutions
285 - Process flowcharts
286
2875. **java-javascript-dotnet-guide.md** (1,517 lines)
288 - Documentation comments structure
289 - Language-specific tags (Java, JavaScript, .NET, C/C++)
290 - Templates for classes, methods, enums
291 - Complete code examples
292 - Best practices by language
293
2946. **developer-guides.md** (704 lines)
295 - Guide structure standards
296 - Topic types (concept, reference, task)
297 - Content selection criteria
298 - Code sample standards (compilable, concise, commented)
299 - Best practices
300
3017. **deprecation-policy.md** (664 lines)
302 - API lifecycle states (beta, active, deprecated, decommissioned)
303 - Timeline requirements (12+ months support, 24+ months lifespan)
304 - Required metadata (x-sap-stateInfo, artifact.json)
305 - Decommission process
306 - Complete examples
307
3088. **glossary-resources.md** (472 lines)
309 - Complete terminology definitions (API, OData, OpenAPI, etc.)
310 - External resource links (standards, tools, SAP resources)
311 - Quick reference tables
312 - Tool documentation links
313
314 - Content extraction and organization tracking
315 - Source file mapping from SAP documentation
316 - Consolidation and adaptation notes
317
318## Bundled Resources
319
320This skill includes comprehensive documentation and templates organized for optimal use:
321
322### Reference Guides (`references/`)
323- 9 detailed reference files (10,861 total lines)
324- Complete coverage of SAP API Style Guide standards
325- Progressive disclosure architecture for efficient loading
326
327### Template Files (`templates/`)
3281. **rest-api-overview-template.md** (217 lines) - Level 1 REST overview
3292. **rest-api-method-template.md** (477 lines) - Level 2 REST method details
3303. **odata-service-overview-template.md** (411 lines) - Level 1 OData service
3314. **odata-resource-template.md** (557 lines) - Level 2 OData resource
3325. **odata-operation-template.md** (681 lines) - Level 3 OData operation
333
334Total: 2,343 lines of ready-to-use templates
335
336## Instructions for Use
337
338### Step 1: Identify API Type
339
340Determine if you're documenting REST, OData, Java, JavaScript, .NET, or C/C++ API.
341
342### Step 2: Choose Approach
343
344**Auto-Generated**: Write documentation comments in source code → Use appropriate tags → Submit for review
345
346**Manual**: Select template from `templates/` → Customize [placeholders] → Follow hierarchy → Validate with checklist
347
348### Step 3: Apply Standards
349
350Consult appropriate reference file:
351- **Naming**: `naming-conventions.md`
352- **Descriptions**: `rest-odata-openapi-guide.md` or `java-javascript-dotnet-guide.md`
353- **Quality**: `quality-processes.md`
354- **Deprecation**: `deprecation-policy.md`
355
356### Step 4: Quality Check
357
358Before publishing:
3591. Review against API Quality Checklist (`quality-processes.md`)
3602. Verify naming conventions (`naming-conventions.md`)
3613. Check character limits (see Quick Reference Tables above)
3624. Validate no sensitive data in examples
3635. Test all code examples
3646. Verify links work
3657. Obtain UA developer review
366
367### Step 5: Publish
368
369- **REST/OData**: Submit to SAP API Business Hub
370- **Java/JavaScript/.NET**: Generate with appropriate tool (Javadoc, JSDoc, DocFX)
371- **Developer Guides**: Publish to SAP Help Portal or product documentation
372
373## Common Pitfalls to Avoid
374
375**Naming**:
376- ❌ Including "API": ~~"Custom Forms APIs"~~ → ✅ "Custom Forms"
377- ❌ Using "SAP" prefix: ~~"SAP Document Approval"~~ → ✅ "Document Approval"
378- ❌ Using verbs: ~~"Configuring Portal"~~ → ✅ "Portal Configuration"
379
380**Descriptions**:
381- ❌ Second person: ~~"This operation creates..."~~ → ✅ "Creates a new user"
382- ❌ Generic responses: ~~"No content"~~ → ✅ "Product is out of stock"
383- ❌ Repeating summary in description
384
385**Documentation**:
386- ❌ Skipping UA review
387- ❌ Including sensitive data in examples
388- ❌ Missing required tags
389- ❌ Inconsistent terminology
390
391See individual reference files for complete anti-patterns and fixes.
392
393## Common Issues
394
395| Issue | Correction |
396|-------|------------|
397| API names use verbs or redundant "API" suffixes | Apply the naming rules in `references/naming-conventions.md` before writing descriptions. |
398| OpenAPI descriptions are too generic | Use operation-specific outcomes, error cases, and state information from `references/rest-odata-openapi-guide.md`. |
399| Documentation contains sensitive sample data | Replace tenant, user, token, and customer data with neutral examples before publishing. |
400| Deprecation metadata is missing | Add `x-sap-stateInfo` and migration guidance from `references/deprecation-policy.md`. |
401
402## External Resources
403
404### Standards
405- **OpenAPI Specification**: [https://spec.openapis.org/oas/latest.html](https://spec.openapis.org/oas/latest.html)
406- **OData v4.01**: [https://www.odata.org/documentation/](https://www.odata.org/documentation/)
407- **Javadoc**: [https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
408- **JSDoc 3**: [https://jsdoc.app/](https://jsdoc.app/)
409- **Doxygen**: [https://www.doxygen.nl/](https://www.doxygen.nl/)
410
411### SAP Resources
412- **SAP API Business Hub**: [https://api.sap.com/](https://api.sap.com/)
413- **SAP Developer Center**: [https://developers.sap.com/](https://developers.sap.com/)
414- **SAP Help Portal**: [https://help.sap.com/](https://help.sap.com/)
415- **SAP Community**: [https://community.sap.com/](https://community.sap.com/)
416
417### Source
418- **SAP API Style Guide**: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide)
419
420## Updates and Maintenance
421
422**Source Version**: SAP API Style Guide 2025.01 (verified against commit 902247f)
423
424**Recent Changes**:
425- Source repository updated 2025-10-28
426- Reference file line counts verified and updated
427- Added comprehensive Table of Contents for navigation
428- Added Bundled Resources section for content discovery
429
430**To Update This Skill**:
4311. Check source repository for changes: [https://github.com/SAP-docs/api-style-guide](https://github.com/SAP-docs/api-style-guide)
4322. Review "What's New in the Style Guide"
4333. Update affected reference files
4344. Update templates if standards changed
4355. Update "Last Verified" date
436
437**Quarterly Review Recommended**: Check for updates every 3 months
438
439**Next Review**: 2026-02-27
440
441---
442
443**Skill Version**: 2.4.1
444**Last Updated**: 2026-06-14
445**License**: GPL-3.0
446**Maintainer**: Eduard Jiglau | [hello@sap-ai-skills.com](mailto:hello@sap-ai-skills.com) | [sap-ai-skills.com](https://sap-ai-skills.com) | [https://github.com/secondsky/sap-skills](https://github.com/secondsky/sap-skills)