sap-api-style

SAP API スタイルガイド

関連スキル

• 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 のドキュメントと統合パターンに使用します

目次

1. 概要
2. このスキルを使用する場面
3. 簡易判断ツリー
4. 基本原則
5. クイックリファレンステーブル
6. 利用可能なテンプレート
7. リファレンスファイル
8. 使用手順
9. 避けるべきよくある落とし穴
10. 外部リソース
11. 更新とメンテナンス
12. よくある問題

概要

このスキルでは、SAP API スタイルガイドの公式標準に従って SAP API のドキュメントを作成するための包括的なガイダンスを提供します。SAP エコシステム全体で使用される主要な API タイプとドキュメント作成方法を網羅しています。

ドキュメントのソース：https://github.com/SAP-docs/api-style-guide（76 ファイルを抽出）

このスキルを使用する場面

次の場合に、このスキルを使用します。

• REST、OData、Java、JavaScript、.NET、C/C++ API のAPI ドキュメントを作成する
• SAP API Business Hub 向けのOpenAPI 仕様を記述する
• SAP の命名規則に準拠しているか、API 名をレビューする
• 適切な形式でAPI パラメーター、レスポンス、オペレーションを記述する
• SAP テンプレートを使用してAPI の手動ドキュメントを作成する
• ソースコードにドキュメントコメントを記述する（Javadoc、JSDoc、XML コメント）
• SAP のライフサイクルポリシーに従ってAPI の非推奨化を実施する
• 開発者向けガイドまたはサービスドキュメントを作成する
• API ドキュメントの品質チェックを実施する
• SAP API Business Hub に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

タスクは？

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

基本原則

1. SAP API 間での一貫性

すべての SAP API ドキュメントでは、一貫した規則に従います。

• 命名：言語に応じた形式（camelCase、PascalCase、kebab-case）
• 構造：明確なナビゲーションを備えた階層構造
• 書式：文頭は大文字、文末はピリオド
• 言語：アメリカ英語

2. API タイプ固有の標準

API の種類	標準	ツール	ドキュメント
REST	OpenAPI 3.0.3	Swagger	仕様
OData	v4.01、v3.0、v2.0	各種	OData.org
Java	Javadoc	javadoc	Oracle
JavaScript	JSDoc 3	jsdoc	JSDoc.app
.NET	XML コメント	DocFX	Microsoft
C/C++	Doxygen	doxygen	Doxygen.nl

3. 段階的な情報開示

ドキュメントは階層的に構成します。

• 概要レベルの説明では、背景情報とナビゲーションを提供します
• 詳細なリファレンスでは、特定の API、メソッド、オペレーションを説明します
• 例とテンプレートでは、実践的な使い方を示します

4. 品質基準

すべてのドキュメントは、次の要件を満たす必要があります。

• ✅ User Assistance（UA）の開発者によるレビューを受ける
• ✅ 一貫した命名と用語を使用する
• ✅ パラメーターとレスポンスの説明を漏れなく含める
• ✅ 例に機密データを含めない
• ✅ 動作するコード例を提供する
• ✅ リンクと相互参照を正確に保つ

クイックリファレンステーブル

文字数制限

要素	制限	用途
API タイトル	80	OpenAPI の info.title
API の短い説明	180	x-sap-shortText
パッケージの短い説明	250	パッケージタイルの説明
操作の概要	255	操作の概要行
説明	1024	一般的な説明

API の命名規則

一般規則（すべての API タイプ）：

• ❌ 名前に「API」を含めないでください：「カスタムフォーム API」 → ✅ 「カスタムフォーム」
• ❌ 「SAP」を接頭辞にしないでください：「SAP 文書承認」 → ✅ 「文書承認」
• ❌ 動詞を使わないでください：「ポータルの設定」 → ✅ 「ポータル設定」
• ✅ 単語を適切に大文字で表記してください
• ✅ 技術的な詳細（REST、OData など）は避けてください

言語ごとの完全な規則については、references/naming-conventions.md を参照してください。

一般的なドキュメントタグ

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 ライフサイクルの状態

状態	定義	サポート	必須のメタデータ
ベータ	本番前のテスト	保証なし	state: beta
アクティブ	本番環境で利用可能（デフォルト）	全面的なサポート	任意
非推奨	後継に置き換え済み	12 か月以上	state、deprecationDate、successorApi
廃止	完全に終了	なし	ドキュメントの削除

完全なスケジュールとプロセス要件については、references/deprecation-policy.md を参照してください。

大規模なリファレンスの検索と絞り込み

大規模なリファレンスを読み込む前に検索してください。rg -n "<resource|operation|parameter|description|template|deprecation|x-sap-stateInfo>" references/*.md を使って該当する規則を特定し、関連する箇所だけを開いてください。

• 手動で作成する REST/OData ドキュメントテンプレートについては、references/manual-templates-guide.md を使用してください。REST API Template、OData Operation Template、field requirements、method、またはリソース名で検索してください。
• OpenAPI、OData、操作の説明、レスポンス、パラメーター、SAP API Business Hub の公開チェックについては、references/rest-odata-openapi-guide.md を使用してください。
• リソース、操作、パッケージ、クラス、メソッド、パラメーター、列挙型、定数の命名については、references/naming-conventions.md を使用してください。
• Javadoc、JSDoc、XML ドキュメントコメント、ネイティブ SDK のドキュメントタグについては、references/java-javascript-dotnet-guide.md を使用してください。
• ライフサイクルの状態、移行ガイダンス、x-sap-stateInfo については、references/deprecation-policy.md を使用してください。
• レビューチェックリスト、ゲート、ドキュメント品質ワークフローについては、references/quality-processes.md を使用してください。

利用可能なテンプレート

すぐに使えるテンプレートは templates/ ディレクトリにあります。

REST API テンプレート（2 階層）

1. rest-api-overview-template.md - リソースレベルの概要
2. rest-api-method-template.md - 個々のエンドポイントの詳細

OData API テンプレート（3 階層）

1. odata-service-overview-template.md - サービス全体の概要
2. odata-resource-template.md - 個々のリソース／エンティティセット
3. odata-operation-template.md - 特定の操作の詳細

すべてのテンプレートには、次の内容が含まれています：

• 明確な「使用方法」の手順
• カスタマイズ用の［プレースホルダーテキスト］
• 完全なセクション構成
• 動作する例
• インラインガイダンス

リファレンスファイル

利用可能な完全ガイド

1. rest-odata-openapi-guide.md（2,800 行）

   • OpenAPI 仕様に関する包括的なガイドライン
   • パッケージ、API、操作の説明
   • パラメーター、レスポンス、コンポーネント
   • セキュリティスキーム、タグ、外部ドキュメント
   • 文字数制限とアンチパターン

2. manual-templates-guide.md（2,765 行）

   • REST API テンプレート（2 階層）
   • OData API テンプレート（3 階層）
   • テンプレートの完全な構造
   • 項目ごとの要件
   • ベストプラクティスと例

3. naming-conventions.md（2,059 行）

   • REST/OData の命名規則（リソース、パラメーター、URI）
   • ネイティブライブラリの命名規則（クラス、メソッド、定数、パッケージ）
   • 言語固有の規約
   • よくある間違いと修正方法
   • 判断フローと参照表

4. quality-processes.md（1,774 行）

   • API 品質チェックリストの全項目
   • レビューワークフロー（開発者と UA の連携）
   • 開発チーム向けガイドライン
   • よくあるレビュー指摘事項と解決策
   • プロセスフローチャート

5. java-javascript-dotnet-guide.md（1,517 行）

   • ドキュメントコメントの構成
   • 言語固有のタグ（Java、JavaScript、.NET、C/C++）
   • クラス、メソッド、列挙型のテンプレート
   • コード例の全項目
   • 言語別のベストプラクティス

6. developer-guides.md（704 行）

   • ガイド構成の標準
   • トピックの種類（概念、リファレンス、タスク）
   • コンテンツ選定基準
   • コードサンプルの標準（コンパイル可能、簡潔、コメント付き）
   • ベストプラクティス

7. deprecation-policy.md（664 行）

   • API ライフサイクルの状態（ベータ、アクティブ、非推奨、廃止）
   • タイムライン要件（12 か月以上のサポート、24 か月以上のライフスパン）
   • 必須のメタデータ（x-sap-stateInfo、artifact.json）
   • 廃止プロセス
   • 完全な例

8. glossary-resources.md（472 行）

   • 用語の定義（API、OData、OpenAPI など）

   • 外部リソースへのリンク（標準、ツール、SAP リソース）

   • クイックリファレンス表

   • ツールドキュメントへのリンク

   • コンテンツの抽出と整理に関する記録

   • SAP ドキュメントのソースファイル対応表

   • 統合および適用に関する注記

同梱リソース

このスキルには、最適に活用できるよう整理された包括的なドキュメントとテンプレートが含まれています。

リファレンスガイド（references/）

• 詳細なリファレンスファイル 9 件（合計 10,861 行）
• SAP API Style Guide 標準を網羅
• 効率的な読み込みを実現する段階的開示のアーキテクチャ

テンプレートファイル（templates/）

1. rest-api-overview-template.md（217 行）- レベル 1 の REST 概要
2. rest-api-method-template.md（477 行）- レベル 2 の REST メソッド詳細
3. odata-service-overview-template.md（411 行）- レベル 1 の OData サービス
4. odata-resource-template.md（557 行）- レベル 2 の OData リソース
5. odata-operation-template.md（681 行）- レベル 3 の OData 操作

合計：すぐに使えるテンプレート 2,343 行

使用手順

ステップ 1：API の種類を特定する

ドキュメントを作成する対象が、REST、OData、Java、JavaScript、.NET、C/C++ のいずれの API かを判断します。

ステップ 2：アプローチを選択する

自動生成：ソースコードにドキュメントコメントを記述 → 適切なタグを使用 → レビューに提出

手動：templates/ からテンプレートを選択 → [プレースホルダー] をカスタマイズ → 階層構造に従う → チェックリストで検証

ステップ 3：標準を適用する

適切なリファレンスファイルを参照します。

• 命名：naming-conventions.md
• 説明：rest-odata-openapi-guide.md または java-javascript-dotnet-guide.md
• 品質：quality-processes.md
• 非推奨化：deprecation-policy.md

ステップ 4：品質を確認する

公開する前に、次の項目を確認します。

1. API 品質チェックリスト（quality-processes.md）に照らして確認する
2. 命名規則（naming-conventions.md）を検証する
3. 文字数制限を確認する（上記のクイックリファレンス表を参照）
4. 例に機密データが含まれていないことを確認する
5. すべてのコード例をテストする
6. リンクが機能することを確認する
7. UA 開発者によるレビューを受ける

ステップ 5：公開

• REST/OData：SAP API Business Hub に登録します
• Java/JavaScript/.NET：適切なツール（Javadoc、JSDoc、DocFX）を使用して生成します
• 開発者ガイド：SAP Help Portal または製品ドキュメントで公開します

よくある避けるべき落とし穴

命名：

• ❌ 「API」を含める：「Custom Forms APIs」 → ✅ 「Custom Forms」
• ❌ 「SAP」接頭辞を使用する：「SAP Document Approval」 → ✅ 「Document Approval」
• ❌ 動詞を使用する：「Configuring Portal」 → ✅ 「Portal Configuration」

説明：

• ❌ 二人称：「This operation creates...」 → ✅ 「Creates a new user」
• ❌ 一般的な応答：「No content」 → ✅ 「Product is out of stock」
• ❌ 説明で概要を繰り返す

ドキュメント：

• ❌ UA レビューを省略する
• ❌ 例に機密データを含める
• ❌ 必須タグが不足している
• ❌ 用語に一貫性がない

アンチパターンと修正方法の詳細については、各リファレンスファイルを参照してください。

よくある問題

問題	修正方法
API 名に動詞や冗長な「API」接尾辞が使われている	説明を書く前に、references/naming-conventions.md の命名規則を適用します。
OpenAPI の説明が一般的すぎる	references/rest-odata-openapi-guide.md の操作固有の結果、エラーケース、状態情報を使用します。
ドキュメントに機密性の高いサンプルデータが含まれている	公開前に、テナント、ユーザー、トークン、顧客のデータを中立的な例に置き換えます。
非推奨化のメタデータがない	references/deprecation-policy.md の x-sap-stateInfo と移行ガイダンスを追加します。

外部リソース

標準

• OpenAPI Specification：https://spec.openapis.org/oas/latest.html
• OData v4.01：https://www.odata.org/documentation/
• Javadoc：https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html
• JSDoc 3：https://jsdoc.app/
• Doxygen：https://www.doxygen.nl/

SAP リソース

• SAP API Business Hub：https://api.sap.com/
• SAP Developer Center：https://developers.sap.com/
• SAP Help Portal：https://help.sap.com/
• SAP Community：https://community.sap.com/

ソース

• SAP API Style Guide：https://github.com/SAP-docs/api-style-guide

更新とメンテナンス

ソースバージョン：SAP API Style Guide 2025.01（コミット 902247f と照合済み）

最近の変更：

• ソースリポジトリを 2025-10-28 に更新
• リファレンスファイルの行数を確認して更新
• ナビゲーション用の包括的な目次を追加
• コンテンツを探しやすくするため、バンドルリソースのセクションを追加

このスキルを更新するには：

1. ソースリポジトリの変更を確認します：https://github.com/SAP-docs/api-style-guide
2. 「What's New in the Style Guide」を確認します
3. 該当するリファレンスファイルを更新します
4. 標準が変更された場合はテンプレートを更新します
5. 「Last Verified」の日付を更新します

四半期ごとのレビューを推奨：3 か月ごとに更新を確認してください

次回レビュー：2026-02-27

---

スキルバージョン：2.4.1 最終更新日：2026-06-14 ライセンス：GPL-3.0 メンテナー：Eduard Jiglau | [email protected] | sap-ai-skills.com | https://github.com/secondsky/sap-skills