This skill provides comprehensive guidance for documenting SAP APIs following official SAP API Style Guide standards. It should be used when creating or reviewing API documentation for REST, OData, Java, JavaScript, .NET, or C/C++ APIs. The skill covers naming conventions, documentation comments, OpenAPI specifications, quality checklists, deprecation policies, and manual documentation templates. It ensures consistency with SAP API Business Hub standards and industry best practices. Keywords: SAP API, REST, OData, OpenAPI, Swagger, Javadoc, JSDoc, XML documentation, API Business Hub, API naming, API deprecation, x-sap-stateInfo, Entity Data Model, EDM, documentation tags, API quality, API templates
/plugin marketplace add secondsky/sap-skills/plugin install sap-api-style@sap-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdreferences/deprecation-policy.mdreferences/developer-guides.mdreferences/glossary-resources.mdreferences/java-javascript-dotnet-guide.mdreferences/manual-templates-guide.mdreferences/naming-conventions.mdreferences/quality-processes.mdreferences/rest-odata-openapi-guide.mdtemplates/odata-operation-template.mdtemplates/odata-resource-template.mdtemplates/odata-service-overview-template.mdtemplates/rest-api-method-template.mdtemplates/rest-api-overview-template.mdThis 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
Use this skill when:
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
All SAP API documentation follows consistent conventions:
| 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 |
Documentation organized hierarchically:
All documentation must:
| 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 |
General Rules (all API types):
See references/naming-conventions.md for complete language-specific rules.
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=""> - ExceptionSee references/java-javascript-dotnet-guide.md for complete tag reference.
| 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.
Ready-to-use templates in templates/ directory:
All templates include:
rest-odata-openapi-guide.md (2,800 lines)
manual-templates-guide.md (2,765 lines)
naming-conventions.md (2,059 lines)
quality-processes.md (1,774 lines)
java-javascript-dotnet-guide.md (1,517 lines)
developer-guides.md (704 lines)
deprecation-policy.md (664 lines)
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
This skill includes comprehensive documentation and templates organized for optimal use:
references/)templates/)Total: 2,343 lines of ready-to-use templates
Determine if you're documenting REST, OData, Java, JavaScript, .NET, or C/C++ API.
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
Consult appropriate reference file:
naming-conventions.mdrest-odata-openapi-guide.md or java-javascript-dotnet-guide.mdquality-processes.mddeprecation-policy.mdBefore publishing:
quality-processes.md)naming-conventions.md)Naming:
Descriptions:
Documentation:
See individual reference files for complete anti-patterns and fixes.
Source Version: SAP API Style Guide 2025.01 (verified against commit 902247f)
Recent Changes:
To Update This Skill:
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
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.