secondsky/sap-skills

sap-api-style

This skill provides comprehensive guidance for documenting SAP APIs following the SAP API Style Guide standards.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/secondsky/sap-skills --skill sap-api-style

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

  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
  12. 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 TypeStandardToolDocumentation
RESTOpenAPI 3.0.3SwaggerSpec
ODatav4.01, v3.0, v2.0VariousOData.org
JavaJavadocjavadocOracle
JavaScriptJSDoc 3jsdocJSDoc.app
.NETXML CommentsDocFXMicrosoft
C/C++DoxygendoxygenDoxygen.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

ElementLimitUse Case
API Title80info.title in OpenAPI
API Short Text180x-sap-shortText
Package Short Desc250Package tile description
Operation Summary255Operation summary line
Description1024General 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

StateDefinitionSupportMetadata Required
BetaPre-production testingNo guaranteesstate: beta
ActiveProduction-ready (default)Full supportOptional
DeprecatedReplaced by successor12+ monthsstate, deprecationDate, successorApi
DecommissionedFully retiredNoneDocument 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)

  1. rest-api-overview-template.md - Resource-level overview
  2. rest-api-method-template.md - Individual endpoint details

OData API Templates (3-Level)

  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

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
  1. 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
  1. 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
  1. 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
  1. 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
  1. developer-guides.md (704 lines)
  • Guide structure standards
  • Topic types (concept, reference, task)
  • Content selection criteria
  • Code sample standards (compilable, concise, commented)
  • Best practices
  1. 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
  1. 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/)

  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

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:

  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

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

IssueCorrection
API names use verbs or redundant "API" suffixesApply the naming rules in references/naming-conventions.md before writing descriptions.
OpenAPI descriptions are too genericUse operation-specific outcomes, error cases, and state information from references/rest-odata-openapi-guide.md.
Documentation contains sensitive sample dataReplace tenant, user, token, and customer data with neutral examples before publishing.
Deprecation metadata is missingAdd 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:

  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: 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

같은 저장소의 Skills

더 많은 Skills

모든 Skills
secondsky
커뮤니티

sap-hana-cli

Assists with SAP HANA Developer CLI (hana-cli) for database development and administration. Use when: installing hana-cli, connecting to SAP HANA databases, inspecting database objects (tables, views, procedures, functions), managing HDI containers, executing SQL queries, converting metadata to CDS/EDMX/OpenAPI formats, managing SAP HANA Cloud instances, working with BTP CLI integration, or troubleshooting hana-cli commands. Covers: 91 commands, 17+ output formats, HDI container management, clou

1시간 설치 수
1
GitHub Stars
501
업데이트
11월 13일
secondsky
커뮤니티

sap-sqlscript

This skill should be used when the user asks to "write a SQLScript procedure", "create HANA stored procedure", "implement AMDP method", "optimize SQLScript performance", "handle SQLScript exceptions", "debug HANA procedure", "create table function", "inspect a browser-based Datasphere SQL editor with Microsoft Edge CDP", or mentions SQLScript, SAP HANA procedures, AMDP, EXIT HANDLER, or code-to-data paradigm. Comprehensive SQLScript development guidance for SAP HANA database programming includin

1시간 설치 수
1
GitHub Stars
501
업데이트
11월 13일
secondsky
커뮤니티

sap-sac-planning

SAP Analytics Cloud (SAC) planning guidance for planning models, planning-enabled stories, data actions, multi actions, version management, data locking, calendar/input workflows, allocations, value driver trees, BPC live planning, and Seamless Planning with SAP Datasphere. Use this for planning design, planning APIs, data action debugging, planning performance reviews, and authenticated SAC planning story triage in Microsoft Edge via CDP; use sap-sac-scripting for non-planning SAC scripts and s

1시간 설치 수
2
GitHub Stars
497
업데이트
11월 13일
secondsky
커뮤니티

claude-automation-recommender

Analyze a codebase and recommend Claude Code automations (hooks, subagents, skills, plugins, MCP servers). Use when user asks for automation recommendations, wants to optimize their Claude Code setup, mentions improving Claude Code workflows, asks how to first set up Claude Code for a project, or wants to know what Claude Code features they should use.

1시간 설치 수
1
GitHub Stars
497
업데이트
11월 13일