--- schema_version: "1" id: 1c445ab676eaa91915361a8b56e6649bd1264a525448dfcdfafc56779d750497 title: API 仕様とフラグメントの設計 collection: mulesoft version: current locale: ja-jp portal_url: https://docs.salesforce.com/mulesoft/current/ja-jp/anypoint-code-builder/des-designing-api-specs.md canonical_url: https://docs.mulesoft.com/jp/anypoint-code-builder/des-designing-api-specs source_site: docs.mulesoft.com content_type: documentation content_hash: 305e06baeeabc0b13e1c05a9371a673bd3a4f5276f87af69c8c4914d3a087c68 description: MuleSoft Documentation Site latest: true --- # API 仕様とフラグメントの設計 **進行中のベータリリース**​: **クラウド IDE は進行中のベータリリースです**​。ベータ状態での Anypoint Code Builder の使用には、IDE で入手できる、該当するベータサービス契約条件が適用されます。 Anypoint Code Builder を使用して、新しい API 仕様の作成、設計、テスト、および Exchange へのパブリッシュを行います。 API 仕様を設計するプロセスは、次のとおりです。 1. [API 仕様を作成またはインポートしてテストします](https://docs.mulesoft.com/jp/anypoint-code-builder/des-create-api-specs)​。 2. [必要に応じて、フラグメントを作成して仕様に追加します](https://docs.mulesoft.com/jp/anypoint-code-builder/des-create-api-fragments)​。 3. [API 仕様を Exchange にパブリッシュします](https://docs.mulesoft.com/jp/anypoint-code-builder/des-publish-api-spec-to-exchange)​。 ソース管理オプションについては、​[SCM for API Design Projects (API 設計プロジェクトの SCM)](https://docs.mulesoft.com/jp/anypoint-code-builder/start-scm#anypoint-scm)​ を参照してください。 ## [](#supported-spec-languages)API 仕様でサポートされる OAS および RAML バージョン サポートされる OAS および RAML バージョンは、次のとおりです。 - OAS 2.0 (JSON) - OAS 2.0 (YAML) - OAS 3.0 (JSON) - OAS 3.0 (YAML) - RAML 1.0 - RAML 0.8 サポートされる AsyncAPI バージョンは、次のとおりです。 - AsyncAPI 2.6 (JSON) - AsyncAPI 2.6 (YAML) ## [](#supported-fragment-languages)API フラグメントでサポートされる仕様言語 API フラグメントを API 仕様内に作成するか、含めるか、参照します。 API フラグメントでサポートされる API 仕様言語と構文は、次のとおりです。 - OAS 3.0 - YAML - JSON - RAML 1.0 これらの種別の詳細は、RAML 1.0 仕様を参照してください。 - 特性 - リソース - ライブラリ - データ型 - ユーザードキュメント - 例 - JSON スキーマ - Avro 1.9.0 スキーマ ## [](#resource-reqs)デスクトップ IDE の最小リソース要件 API 仕様を解析するときに、デスクトップ IDE はコンピューターのリソースに依存します。問題を回避するには、コンピューターに次の最小リソースがあることを確認します。 - 8GB RAM - Ryzen シリーズ 5 / Intel i5 CPU 以上 パーサーの最適なパフォーマンスを実現するには、設計プロジェクト内のすべてのファイルの合計プロジェクトサイズを 500 KB 未満に抑えます。 プロジェクトサイズが 1.5 MB を超えると、検証時間に重大な影響を与えます。 ## [](#best-practices)ベストプラクティス 一般的な問題を回避するには、次のガイドラインに従います。 - 可能な場合は、フラグメントを短い再利用可能な連動関係に分割します。 - 同じ連動関係の 1 つのバージョンのみを保持します。 - 一度に 1 つのブラウザータブのみを開いたままにします。 このベストプラクティスは、クラウド IDE にのみ適用されます。 - OAS または RAML API 仕様を設計する前に、​[OAS 仕様のベストプラクティス](#apid-best-practices-oas)​または​[RAML 仕様のベストプラクティス](#apid-best-practices-raml)​を確認します。 ### [](#apid-best-practices-oas)OAS 仕様のベストプラクティス - `$ref`​ プロパティを使用して、再利用可能なコンポーネントを定義します。解析効率を向上させるには、コンポーネント定義を複製する代わりに、API 仕様から各コンポーネントを参照します。次に例を示します。 components: schemas: User: type: object properties: id: type: integer paths: /users: get: responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/User' - 可能な場合は、より単純な型を使用してデータを表現します。不要なネストや複雑な型は避けてください。次に例を示します。 properties: age: type: integer # Prefer simple types over complex types like objects - 解析効率を向上させるには、値の固定セットを使用する項目の ​`enum`​ プロパティを使用します。 properties: status: type: string enum: \[active, inactive\] - オブジェクトに単純なネストを使用して構造を簡略化し、読みやすさと解析効率を改善します。 \# Good properties: name: type: string address: type: string # Avoid properties: user: type: object properties: profile: type: object properties: name: type: string - 追加情報を提供するには、レスポンスボディの代わりに ​`response`​ ヘッダーを使用します。次に例を示します。 responses: '200': description: Successful response headers: X-Rate-Limit-Limit: description: The number of requests allowed in the current period schema: type: integer - 簡潔で短い例を指定します。 Book: type: string example: "Explain the string with as few words as possible." - 結合型プロパティを使用する場合、結合型オブジェクト項目を表すには ​`oneOf`​ を使用し、交型の複合オブジェクトと項目を表すには ​`allOf`​ を使用し、複数の考えられるデータ構造でプロパティを定義する場合には ​`anyOf`​ を使用します。 ### [](#apid-best-practices-raml)RAML 仕様のベストプラクティス - RAML フラグメントを抽出するときは、最初に各フラグメントをローカル宣言としてインポートします。 フラグメントファイルを作成し、そのフラグメントを Anypoint Exchange にパブリッシュする前に、ローカルフラグメントファイルをインポートして、フラグメントが期待どおりに機能することを検証します。フラグメントが機能する場合は、フラグメントを Exchange にパブリッシュして、フラグメントを複製する代わりに API 仕様で再利用できるようにします。 - データ型を宣言として再利用します。 - 必要な場合にのみ継承を使用します。 Car: description: This is a car properties: brand: string model: string example: brand: Toyota model: Corolla Person: properties: owns: Car - 短い結合を使用します。 Person: type: Employee | Customer - 単純な特性を使用し、特性とリソース種別のプロパティを組み合わせないようにします。 /basic: type: {resourceTypes.fhirResourceType: { postExample : !include /examples/requests/post\_resource.json, getExample : !include /examples/responses/get\_resource.json, bundleName : basic.BasicBundle } } /\_search: get: is: \[ searchParams \] post: is: \[ POSTSearchParams \] ## [](#anypoint-scm)API 設計プロジェクトのソース制御 ソース制御管理 (SCM) を使用して、設計、インテグレーション、実装プロジェクトを保存および共有します。 API 設計プロジェクトのソース制御オプションは、プロジェクトの作成方法とタイミングによって異なります。 - 2024 年 2 月リリース以降、Anypoint Code Builder で ​**\[Design an API (API を設計)\]**​ (​[「新しい API 仕様プロジェクトを作成する」](https://docs.mulesoft.com/jp/anypoint-code-builder/des-create-api-specs#design-new-api-spec)​を参照) またはコマンド ​`MuleSoft: Design an API`​ を使用して最初から作成した設計プロジェクトでは、MuleSoft VCS を使用して変更を保存および同期しなくなります。 - [Design Center から Anypoint Code Builder にインポート](https://docs.mulesoft.com/jp/anypoint-code-builder/des-create-api-specs#import-spec)​されたか、2024 年 2 月リリースより前に Anypoint Code Builder で作成された API 設計プロジェクトは、MuleSoft VCS に自動的に接続され、対応する設計プロジェクトと同期できるようになります。 独自のリモートリポジトリを使用する場合は、GitHub を使用することもできます。MuleSoft VCS のプロジェクトと同期せずに API プロジェクトを GitHub のリポジトリに保存するには、​[「プロジェクトファイルを別のリポジトリにパブリッシュする」](https://docs.mulesoft.com/jp/anypoint-code-builder/start-scm#add-extra-repo)​を参照してください。 ソース制御オプションについては、[ソースファイルの制御](https://docs.mulesoft.com/jp/anypoint-code-builder/start-scm)を参照してください。