forked from karanmalhi/mulesoft-docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #2848 from mulesoft/RH-APID-Revision
Pull in the rewritten topics for API Designer
- Loading branch information
Showing
24 changed files
with
604 additions
and
191 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| = Add an API Fragment to an API-Specification Project as a Dependency | ||
|
|
||
| In projects for API specifications or API fragments, you can add API fragments as dependencies directly from Anypoint Exchange. | ||
|
|
||
| == About this task | ||
|
|
||
| The fragments are listed in your projects, but they are not present in your projects. Instead, the code editor references them from their online location in Anypoint Exchange. Therefore, although you can include them in your specifications and fragments, you cannot edit them. | ||
|
|
||
| If you export your project, the resulting `.zip` file contains the referenced API fragments. Whenever someone downloads your project as RAML after it is published to Anypoint Exchange, the resulting `.zip` file again contains the referenced API fragments. | ||
|
|
||
| If you export your project to work on it in another editor, edit the referenced API fragments, then try to import the project back into the code editor, the import will fail. | ||
|
|
||
|
|
||
| == Procedure | ||
|
|
||
| . On the left side of the editor, click the *Exchange dependencies* icon, which looks like this: | ||
| + | ||
| image::publish-to-exchange.png[title="Publish to Exchange icon",46,52,align="left"] | ||
| . Click the plus sign that is at the top of the left pane. | ||
| . Select the API fragments that you want to import. You can select from API fragments that are visible to the organizations that you belong to. | ||
|
|
||
|
|
||
| == Result | ||
| The API fragments that you selected are listed in the left pane. You can view their contents by selecting them. When you are ready to continue work on your project, click the *Files* icon. | ||
|
|
||
| The files appear in the folder `exchange-modules`. Within this folder are subfolders that correspond to the parts of the URI for the referenced API fragment. | ||
|
|
||
| [NOTE] | ||
| ==== | ||
| If after you add a dependency on an API fragment an updated version of the fragement is published, and if you want your project to reference the updated version, you must update the dependency. To do so, click the *Exchange dependency* icon, click the dependency, and select *Change version*. In the *Change version* dialog, select the current version. | ||
| ==== |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| = Fork a Project in the RAML Editor | ||
|
|
||
| You can separate new iterations of a project from previous iterations by branching. | ||
|
|
||
| == About this task | ||
|
|
||
| A new branch is a fork of your project and cannot be merged back into the master branch. Anybody who has access to your project can also create branches. | ||
|
|
||
| Even when there are forks of a project, when you open that project the editor opens it to the master branch. If you want to return to a fork that you were working in, you must select that fork. | ||
|
|
||
| You can publish any fork of an API specification to Anypoint Exchange. | ||
|
|
||
| == Procedure | ||
|
|
||
| * To fork a project: | ||
| + | ||
| . Open the project. | ||
| . Click “master” at the top of the code editor. | ||
| . Type a name in the search field and type *Enter*. | ||
| + | ||
| *Result:* The code editor automatically switches to the new fork. | ||
|
|
||
| * To work in a fork of a project: | ||
| + | ||
| . Open the project. | ||
| . Click “master” at the top of the code editor. | ||
| . Select the name of the fork that you want to work in. |
65 changes: 65 additions & 0 deletions
65
design-center/v/1.0/design-create-publish-api-fragment.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| = Create and Publish an API Fragment in the Code Editor in Design Center | ||
|
|
||
| You can create API fragments directly in RAML with the help of code suggestions that appear within the code editor. | ||
|
|
||
|
|
||
| == About this task | ||
|
|
||
| An API fragment is a RAML document that has a version and an identifier, but is not in itself a complete RAML specification. An API fragment is one of the following types defined by RAML.org: | ||
|
|
||
| * Trait | ||
|
|
||
| * Resource Type | ||
|
|
||
| * Library | ||
|
|
||
| * Type | ||
|
|
||
| * User Documentation | ||
|
|
||
| * Example | ||
|
|
||
| * Annotation Type | ||
|
|
||
| * Security Scheme | ||
|
|
||
| == Procedure | ||
|
|
||
| . On the *Projects* page in Design Center, click *Create* and select *API Fragment*. | ||
| . In the *New API Fragment* dialog, type a name for the project and select the type of API fragment that you want to create. Then, click *Create*. | ||
| + | ||
| _Result:_ The code editor opens. The editor is divided into three panels: | ||
| + | ||
| * The left panel lists the files in your project. By default, the editor creates a `.raml` file that has the same name as the project. | ||
| + | ||
| [TIP] | ||
| ==== | ||
| You can create more than one API specification in a single project. If you want to include additional API specifications in your project, click the plus sign in the Files panel to create a new file or click the dots that are next to the plus sign to import a file. | ||
| ==== | ||
| * The central panel displays the editor in which you create your API fragment. | ||
| * The right panel lists the types and resources that are in the API fragment that is displayed in the central panel. | ||
|
|
||
| . Draft your API fragment. | ||
| + | ||
| As you draft, the code editor suggests RAML nodes, methods, and other elements that you can add at the location of your cursor. | ||
| + | ||
| You can import files into your project, either separately or bundled together in .zip files. The files can be RAML 1.0 files, JSON files, or OpenAPI Specification (OAS) 2.0 files. The files can be on your computer or you can specify a URL for them if they are located online. | ||
| + | ||
| For more information about importing files and steps for how to import them, see "Import Files into an API Project", which is linked to from the *See also* section at the end of this topic. | ||
|
|
||
|
|
||
|
|
||
| == What to do next | ||
|
|
||
| You can publish the API fragment to Anypoint Exchange. Click the icon that is in the top-right corner of the code editor to open the *Publish API specification to Exchange* dialog. The icon looks like this: | ||
|
|
||
| image::publish-to-exchange.png[title="Publish to Exchange icon",46,52,align="left"] | ||
|
|
||
| The fragment can then be included as a dependency in an API-specification project. After revising a fragment, update API specifications that use the fragment to include the new version. | ||
|
|
||
| == See also | ||
|
|
||
| * link:/design-center/v/1.0/design-import-files[Import Files into an API Project] |
72 changes: 72 additions & 0 deletions
72
design-center/v/1.0/design-create-publish-api-raml-editor.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| = Create and Publish an API Specification with the Code Editor in Design Center | ||
|
|
||
| You can create API specifications directly in RAML with the help of code suggestions that appear within the code editor. | ||
|
|
||
| == Before you begin | ||
| Within Anypoint Platform, you must be assigned the _Design Center Developer_ permission. | ||
| // What guidance can I give for designing an API specification before using the API Designer? | ||
|
|
||
| == About this task | ||
|
|
||
| An API specification that is written in RAML typically includes the following things: | ||
|
|
||
| * An optional baseURI node at the root of the RAML document | ||
| + | ||
| If you don’t have an implementation of the API and cannot provide a baseURI, you can still test the API using the mocking service baseURI described below. | ||
|
|
||
| * API resources, for example the collection of all customers or a specific customer | ||
|
|
||
| * HTTP methods, such as GET, POST, PUT, and DELETE, allowed on each resource | ||
|
|
||
| * The representation of the request and response messages for each method, | ||
|
|
||
| == Procedure | ||
| . On the *Projects* page in Design Center, click *Create* and select *API Specification*. | ||
| . In the *New API Specification* dialog, name your project and select the option *Start with API Designer* to use the code editor. | ||
| + | ||
| _Result:_ The code editor opens. The editor is divided into three panels: | ||
| + | ||
| * The left panel lists the files in your project. By default, the editor creates a `.raml` file that has the same name as the project. | ||
| + | ||
| [TIP] | ||
| ==== | ||
| You can create more than one API specification in a single project. If you want to include additional API specifications in your project, click the plus sign in the Files panel to create a new file or click the dots that are next to the plus sign to import a file. | ||
| ==== | ||
| * The central panel displays the editor in which you create the API specification. Appearing in the editor when you create a project or start a new API specification are the first two lines of a valid `.raml` file. | ||
| * The right panel lists the types and resources that are in the API specification that is in the central panel. | ||
|
|
||
| . Draft your API specification. | ||
| + | ||
| As you draft, the code editor suggests RAML nodes, methods, and other elements that you can add at the location of your cursor. | ||
| + | ||
| You can also perform these tasks: | ||
| + | ||
| Import files and API fragments into your project:: You can import files, either separately or bundled together in .zip files. The files can be RAML 1.0 files, JSON files, or OpenAPI Specification (OAS) 2.0 files. The files can be on your computer or you can specify a URL for them if they are located online. | ||
| + | ||
| For more information about importing files and steps for how to import them, see "Import Files into an API Project", which is linked to from the *See also* section at the end of this topic. | ||
| + | ||
| For information about adding API fragments to your project, see "Add an API Fragment to an API-Specification Project as a Dependency", which is linked to from the *See also* section at the end of this topic. | ||
| + | ||
| Simulate calls to your API:: Even while you are drafting an API specification, you can simulate calls to endpoints for which you have specified | ||
| + | ||
| * An HTTP status code the API returns, if successful | ||
| * An example of data the actual implementation would return | ||
| + | ||
| For more information, view the topic "Simulate Calls to an API", which is linked to from the *See also* section at the end of this topic. | ||
|
|
||
| Export your API project:: At any time, you can export your project as a `.zip` file, or an API specification from RAML to OAS 2.0. For more information, view the topic "Export Files from an API Project", which is linked to from the *See also* section at the end of this topic. | ||
|
|
||
| == What to do next | ||
| Publish your API specification to Exchange. Click the icon that is in the top-right corner of the code editor to open the *Publish API specification to Exchange* dialog. The icon looks like this: | ||
|
|
||
| image::publish-to-exchange.png[title="Publish to Exchange icon",46,52,align="left"] | ||
|
|
||
|
|
||
| == See also | ||
| * link:/design-center/v/1.0/design-export-files[Export Files from an API Project] | ||
| * link:/design-center/v/1.0/design-import-files[Import Files into an API Project] | ||
| * link:/design-center/v/1.0/design-add-api-dependency[Add an API Fragment to an API-Specification Project as a Dependency] | ||
| * link:/design-center/v/1.0/design-mocking-service[Simulate Calls to an API] |
Oops, something went wrong.