--- schema_version: "1" id: 6391ec5cdc038336a49ee045d7939b54ea37e2adec5c7e63f31a08ea9c522fe2 title: Creating and Using API Spec Fragments collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/anypoint-code-builder/des-create-api-fragments.md canonical_url: https://docs.mulesoft.com/anypoint-code-builder/des-create-api-fragments source_site: docs.mulesoft.com content_type: documentation content_hash: 4b56c1db782e10c0bcaeac0485dd3675e71d2f0b9d6ff89582ccc8c901ee7d43 description: MuleSoft Documentation Site latest: true --- --- product: Anypoint Code Builder version: master --- # Creating and Using API Spec Fragments > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Using Anypoint Code Builder, you can create your own API fragments and publish them to Anypoint Exchange to share with other people, add fragments from Exchange to your API specification, or create fragments in your project to add directly to your API specification. Alternatively, you can create and add a fragment directly in your project without publishing it to Exchange. Anypoint Code Builder supports scaffolding these schema fragment files if they’re referenced from API specs:
AvroJSONRAML

AsyncAPI

Yes

Yes

No

GraphQL

No

No

Yes

OData

No

No

Yes

REST

No

Yes

Yes

SOAP

No

No

Yes

If you add a fragment that isn’t supported, the scaffolder doesn’t add these fragments as project dependencies when you import the spec from Exchange. However, you can scaffold schemas that are specified inline within the spec. The process for adding a fragment from Exchange is: 1. [Add the API fragment from Exchange](#add-fragment-to-project) to your API spec project as a dependency. 2. [Add the API fragment to your API spec](#add-fragments-to-spec) using the `$ref` (OAS and AsyncAPI) or `!include` (RAML) directives. The process for adding a fragment without publishing it to Exchange is: - [Create and add a fragment directly in your project](#create-add-fragment-directly) without publishing it to Exchange. Use these examples to explore the functionality of Anypoint Code Builder: - [`example-oas-fragment`](#example-oas-api-frag) API spec fragment - [`example-oas-api-spec`](#example-oas-api-spec) API spec - [`example-asyncapi-avro-fragment`](#example-avro-api-frag) AsyncAPI spec Avro schema fragment - [`example-asyncapi-spec`](#example-asyncapi-spec) AsyncAPI spec - [`example-asyncapi-spec-inline-avro`](#example-asyncapi-spec-inline-avro) AsyncAPI spec (inline Avro) ## Before You Begin Before adding fragments: - [Set up and access Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/start-acb). - Understand the basics of designing API specifications. To see where adding fragments fits in the journey from API design through deployment, see [Take Your API Specification from Design Through Deployment in Mule](https://docs.mulesoft.com/anypoint-code-builder/tutorials#modular-learning-paths). - Have some familiarity with [business groups](https://docs.mulesoft.com/access-management/business-groups). When you publish your API fragment to Exchange from Anypoint Code Builder, it requests the name of the business group. See [Anypoint Platform Business Groups](https://docs.mulesoft.com/access-management/business-groups). ## Create an API Fragment and Publish it to Exchange The process for creating and publishing API spec fragments is similar to the process for API specs. To create an API spec fragment: 1. In the activity bar, click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-ms-logo.png) (**Anypoint Code Builder**) icon. ![Anypoint Code Builder icon highlighted in the activity bar](/mulesoft/current/en-us/anypoint-code-builder/_images/anypoint-code-builder-view.png) 2. From **Create**, click **Design an API**: ![\*Design an API\* link highlighted in the \*Create\* section](/mulesoft/current/en-us/anypoint-code-builder/_images/design-api-1.png) 3. In **Design an API**, click the **API Fragment** tab: Ensure that you select the **API Fragment** tab. 4. Complete the **API Fragment** form:
Field NameField Value

Project Name

Unique name for your fragment.

This name is used as the fragment title in Exchange and name of the fragment file. For example, if the project name is Example OAS Fragment, the specification file name is example-oas-fragment.

To reuse an existing project name, you must delete the project that is already using the name first. See Deleting API Specs and Fragments.

Project Location

Your home directory or another directory you create.

Don’t create the project within another project directory.

API Specification Language

Select OAS 3.0 (YAML) to use the example in this procedure.

<Language> Syntax

The syntax for the selected language.

Select YAML to use the example in this procedure.

5. Click **Create Project**. If prompted, trust the authors of the files in the folder. When the project is ready for editing, the API fragment project opens in the Explorer view. For example, this OAS 3.0 (YAML) API fragment: ![API Fragment tab on the Design an API page](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-fragment-new.png) 6. Continue designing your API fragment. As you enter elements, use [auto-complete](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#use-autocomplete) (or press Ctrl+Space) to display available options within the context. If you created an OAS 3.0 (YAML) fragment project, you can replace the initial API fragment with the [example](#example-oas-api-frag) code to test adding fragments to a spec. 7. [Publish your fragment to Exchange](https://docs.mulesoft.com/anypoint-code-builder/des-publish-api-spec-to-exchange). The status bar shows the progress. When complete, you see a message that the API fragment successfully published to Exchange. 8. Navigate to Anypoint Platform and log in using your credentials. Show me how - US cloud (non-EU host): [Anypoint Platform (US)](https://anypoint.mulesoft.com/login/) - EU cloud (EU host): [Anypoint Platform (EU)](https://eu1.anypoint.mulesoft.com/login/) 9. Navigate to Anypoint Exchange. Show me how - US cloud (non-EU host): [Exchange (US)](https://anypoint.mulesoft.com/exchange/) - EU cloud (EU host): [Exchange (EU)](https://eu1.anypoint.mulesoft.com/exchange/) Your API specification appears as an API spec fragment type asset in your organization, for example: ![API Spec Fragment in Exchange](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-frag-exchange.png) If your API spec appears on Exchange as a REST API rather than an API spec fragment, check that the `classifier` attribute in the `exchange.json` file in the project folder is set to one of the following, depending on the language: - OAS: `oas-components` - RAML: `raml-fragment` - JSON Schema: `json-schema` If the attribute is set to one of the following, the project is an API spec rather than a fragment: - OAS: `oas` - RAML: `raml` ## Add a Fragment from Exchange to Your Project To add an API spec fragment from Exchange to the project directory so that you can include the fragment in your spec: 1. Open your API spec project file, for example, [`example-oas-spec`](#example-oas-api-spec). 2. Open the Command Palette. Show me how - Use the keyboard shortcuts: - Mac: Cmd+Shift+p - Windows: Ctrl+Shift+p - Select **View** > **Command Palette**. 3. Enter `mulesoft` and select the following command: ```command MuleSoft: Add Fragment dependency from Exchange ``` 4. If prompted, log in to Anypoint Platform. 5. In the **Search for Asset** field, provide the name of the data type asset to add. To search for assets, type the search term and press Enter, for example: ![Search for fragment in Assets from Exchange dropdown](/mulesoft/current/en-us/anypoint-code-builder/_images/des-add-frag-from-exchange.png) 6. Select the fragment from the **Assets From Exchange** menu. 7. Select a version of the fragment. The status bar shows the progress. When complete, you see a message that the selected API fragment was successfully added to the project. 8. Verify that the fragment appears under **Project Dependencies** in Explorer, for example: ![API fragment in the Explorer view](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-frag-dependencies.png) For more information, see [Viewing Project Dependencies](https://docs.mulesoft.com/anypoint-code-builder/start-view-project-dependencies). ## Add an API Fragment to Your API Spec To add an API spec fragment to a spec: 1. Open your API spec project file, for example, [`example-oas-spec`](#example-oas-api-spec). 2. Place the cursor where you want to add the fragment. 3. Depending on the API spec language, select the directive to add the fragment to your specification. - OAS and AsyncAPI specs: Use the `$ref` directive. - RAML specs: Use the `!include` directive. For OAS 3.0 and 3.1 APIs, scaffolding supports `$ref` API fragments from Exchange, including fragments with transitive dependencies. OAS 3.1 requires Mule runtime 4.13 or later and APIkit for Mule 4 1.13.2 or later. DataSense resolves types defined in fragment files when you scaffold into a Mule project that uses a supported Mule runtime version (currently Mule 4.9.19, Mule 4.11.6, and Mule 4.13). - OAS Example - RAML Example - AsyncAPI Example This `$ref` directive adds the `AmericanFlightDataType` from `example-oas-fragment` as a data type: ```YAML schema: $ref: exchange_modules/e91cab06-650b-4634-9c6f-5bc4f4fc4d17/example-oas-fragment/1.0.0/example-oas-fragment.yaml#/components/schemas/AmericanFlightDataType ``` This `!include` directive adds the `AmericanFlight` object from `AmericanFlightDataType.raml` as a data type: ```RAML types: AmericanFlight: !include exchange_modules/68ef9520-24e9-4cf2-b2f5-620025690913/training-american-flight-data-type/1.0.1/AmericanFlightDataType.raml ``` This `$ref` directive adds the `AmericanFlightDataType` from `example-asyncapi-fragment` as a data type: ```YAML payload: $ref: exchange_modules/e91cab06-650b-4634-9c6f-5bc4f4fc4d17/example-asyncapi-fragment/1.0.0/example-asyncapi-fragment.json#/components/schemas/AmericanFlightDataType ``` 4. Use [auto-complete](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#use-autocomplete) (or press Ctrl+Space) to display available options within each context, for example: ![Add the fragment to your API spec](/mulesoft/current/en-us/anypoint-code-builder/_images/des-add-frag-to-spec.png) 5. To reference an element within a component defined in the fragment file: 1. Select the fragment file name. 2. Enter `#/`. 3. Press Ctrl+Space. 4. Select the element from the options, for example: ![Reference an element in the fragment](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-frag-ref-element.png) After adding the fragment to your spec, you can: - Navigate to the dependency: Place the cursor on the fragment reference and press Command+Click. For example: ![Navigate to the fragment dependency](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-frag-goto-dependencies.png) - View the dependency in the API Console: Place the cursor on the fragment reference and click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-api-console.png) (**API Console**) icon to open the fragment in the console. For more information, see [Review Your Spec in the API Console](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs#review-spec-console). ## Create and Add a Fragment Directly in Your Spec To create a fragment in your project and include it in your specification: 1. Open your API spec project file, for example, [`example-oas-spec`](#example-oas-api-spec). 2. In the Explorer view, right-click on an empty space, and create a folder for your fragments, such as `fragments`. 3. In the `fragments` folder, create a new file, such as `my-fragment` and add your fragment code. 4. Place the cursor where you want to add the fragment. 5. Depending on the API spec language, select the directive to add the fragment from the folder to your spec: - OAS and AsyncAPI specs: Use the `$ref` directive. - RAML specs: Use the `!include` directive. - OAS Example - RAML Example - AsyncAPI Example This `$ref` directive adds the `api_key` object from the `my-fragment.yaml` file: ```YAML api-key: $ref: fragments/my-fragment.yaml#/components/securitySchemes/api_key ``` This `!include` directive adds the `AmericanFlightsExample.raml` example: ```RAML examples: output: !include examples/AmericanFlightExample.raml ``` This `$ref` directive adds the `fragments/my-fragment` example: ```YAML payload: $ref: fragments/my-fragment ``` 6. Use [auto-complete](https://docs.mulesoft.com/anypoint-code-builder/start-discover-ui#use-autocomplete) (or press Ctrl+Space) to display available options within each context, for example: ![Add the fragment from a folder to your API spec](/mulesoft/current/en-us/anypoint-code-builder/_images/des-add-frag-from-folder-to-spec.png) 7. To reference an element within a component defined in the fragment file: 1. Select the fragment file name. 2. Enter `#/`. 3. Press Ctrl+Space. 4. Select the element from the options, for example: ![Reference an element in the fragment](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-frag-ref-element.png) After adding the fragment to your spec, you can: - Navigate to the dependency: Place the cursor on the fragment reference and press Command+Click. For example: ![Navigate to the fragment dependency](/mulesoft/current/en-us/anypoint-code-builder/_images/des-api-frag-goto-dependencies.png) - View the dependency in the API Console: Place the cursor on the fragment reference and click the ![](/mulesoft/current/en-us/anypoint-code-builder/_images/icon-api-console.png) (**API Console**) icon to open the fragment in the console. For more information, see [Review Your Spec in the API Console](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs#review-spec-console). ## Example OAS 3.0 (YAML) API Spec Fragment If you created an OAS 3.0 (YAML) fragment project, you can replace the initial API fragment with following example code: Example OAS 3.0 (YAML) API Spec Fragment ```YAML openapi: "3.0.0" info: version: 1.0.0 title: ExampleComponents paths: {} components: schemas: AmericanFlightDataType: type: object description: American Flight Data Type properties: ID: type: number code: type: string price: type: number departureDate: type: string origin: type: string destination: type: string emptySeats: type: number plane: type: object properties: type: type: string totalSeats: type: number example: ID: 1 code: ER38sd price: 400 departureDate: 2017/07/26 origin: CLE destination: SFO emptySeats: 0 plane: type: Boeing 737 totalSeats: 150 ``` ## Example OAS 3.0 (YAML) API Spec If you created an OAS 3.0 (YAML) API spec project, you can replace the initial API spec with following example code to test adding the API spec fragments: Example OAS 3.0 (YAML) API Spec ```YAML openapi: "3.0.0" info: version: 1.0.0 title: Example OAS Spec paths: /flights/{ID}: get: parameters: - name: ID required: true in: path schema: type: string responses: "200": description: "Flight with ID" content: application/json: schema: ``` ## Example AsyncAPI Spec Avro Schema Fragment If you created an Avro schema fragment, you can replace the initial API fragment with following example code: Example AsyncAPI Spec Avro Schema Fragment ```JSON { "name": "AmericanFlightDataType", "type": "record", "fields": [ {"name": "ID", "type": "int", "example": 1}, {"name": "code", "type": "string", "example": "ER38sd"}, {"name": "price", "type": "int", "example": 400}, {"name": "departureDate", "type": "string", "example": "2017/07/26"}, {"name": "origin", "type": "string", "example": "CLE"}, {"name": "destination", "type": "string", "example": "SFO"}, {"name": "emptySeats", "type": "int", "example": 0}, { "name": "plane", "type": { "name": "Plane", "type": "record", "fields": [ {"name": "type", "type": "string"}, {"name": "totalSeats", "type": "int"} ] } } ] } ``` ## Example AsyncAPI Spec If you created an AsyncAPI spec project, you can replace the initial API spec with following example code to test adding the API spec fragments: Example AsyncAPI Spec ```YAML asyncapi: 2.6.0 info: title: Example AsyncAPI Spec version: '1.0.0' channels: myChannel: publish: message: schemaFormat: application/vnd.apache.avro;version=1.9.0 payload: $ref: exchange_modules/e91cab06-650b-4634-9c6f-5bc4f4fc4d17/example-asyncapi-fragment/1.0.0/example-asyncapi-fragment.json ``` ## Example AsyncAPI Spec (Inline Avro) If you created an AsyncAPI spec project, you can replace the initial API spec with following example code to test inlining the API spec fragments: Example AsyncAPI Spec (Inline Avro) ```YAML asyncapi: 2.6.0 info: title: Example AsyncAPI Spec (Inline Avro) version: '1.0.0' channels: myChannel: publish: message: schemaFormat: 'application/vnd.apache.avro;version=1.9.0' payload: name: AmericanFlightDataType type: record fields: - name: ID type: int example: 1 - name: code type: string example: ER38sd - name: price type: int example: 400 - name: departureDate type: string example: 2017/07/26 - name: origin type: string example: CLE - name: destination type: string example: SFO - name: emptySeats type: int example: 0 - name: plane type: name: Plane type: record fields: - name: type type: string - name: totalSeats type: int ``` ## See Also - [Viewing Project Dependencies](https://docs.mulesoft.com/anypoint-code-builder/start-view-project-dependencies) - [Publishing API Projects to Exchange](https://docs.mulesoft.com/anypoint-code-builder/des-publish-api-spec-to-exchange) - [Test Your API Spec Using the Mocking Service](https://docs.mulesoft.com/anypoint-code-builder/des-create-api-specs#test-spec) - [Add the API fragment from Exchange](#add-fragment-to-project) - [Deleting API Specs and Fragments](https://docs.mulesoft.com/anypoint-code-builder/des-delete-api-projects)