Chapter 3. Getting started with Apicurio Studio

Procedure

1. In the Apicurio Studio web console, click Create draft.

2. Complete the wizard to provide the following details for the new draft:

   1. Specify the Draft Coordinates and click Next:

      • Group ID & Draft ID: Use the default empty settings to automatically generate an Draft ID and add the Draft to the default Draft group. Alternatively, you can enter an optional Group ID or Draft ID.
      • Version number: Optionally specify a version number.
      • Type: Use the default Auto-Detect setting to automatically detect the Draft type (not allowed if creating an empty Draft), or select the Draft type from the list, for example, OpenAPI.

   2. Specify the Draft Content and click Next:

      • From template: Choose from the list of templates.

        • From local file: Click Browse, and select a file, or drag and drop a file. For example, my-openapi.json or my-schema.proto. Alternatively, you can enter the file contents in the text box.
        • From URL: Enter a valid and accessible URL, and click Fetch. For example: https://petstore3.swagger.io/api/v3/openapi.json.

   3. Specify the Draft Metadata:

      • Name: Enter an optional friendly name for the first artifact version.
      • Description: Enter an optional description for the first artifact version.
3. Click Create to create the draft. The Draft details view is displayed.

4. To edit the draft, click Edit draft.

   1. Click the Design tab, and optionally edit the draft as follows:

      • Provide a version number and a description.
      • (AsyncAPI only) Define terms of service.
      • Add your contact information: name, email address, and URL.
      • Select a license.
      • (OpenAPI only) Define tags.
      • Define one or more servers.
      • Configure a security scheme.
      • (OpenAPI only) Specify security requirements.
      • (OpenAPI only) Configure vendor extensions.
   2. Click the Source tab, and review the live preview of the draft. The content of the Source tab automatically updates when you edit values on the editor page.
   3. (Optional) To see the changes that you made since the last save, click Actions > Show draft changes.

   4. (Optional) In the left pane of the draft editor, you can add the following items:

      • (OpenAPI only) Resource paths, data types, and responses
      • (AsyncAPI only) Channels, data types, messages, operation traits, and message traits
   5. Click Save.
   6. Use the breadcrumbs to navigate back to the Drafts page.

Procedure

1. In the Apicurio Studio web console, click Create draft.

2. Complete the wizard to provide the following details for the new draft:

   1. Specify the Draft Coordinates and click Next:

      • Group ID & Draft ID: Use the default empty settings to automatically generate an Draft ID and add the Draft to the default Draft group. Alternatively, you can enter an optional Group ID or Draft ID.
      • Version number: Optionally specify a version number.
      • Type: Use the default Auto-Detect setting to automatically detect the Draft type (not allowed if creating an empty Draft), or select the Draft type from the list, for example, Apache Avro.

   2. Specify the Draft Content and click Next:

      • From template: Choose from the list of templates.

        • From local file: Click Browse, and select a file, or drag and drop a file. For example, my-openapi.json or my-schema.proto. Alternatively, you can enter the file contents in the text box.
        • From URL: Enter a valid and accessible URL, and click Fetch. For example: https://petstore3.swagger.io/api/v3/openapi.json.

   3. Specify the Draft Metadata:

      • Name: Enter an optional friendly name for the first artifact version.
      • Description: Enter an optional description for the first artifact version.
3. Click Create to create the draft. The Draft details view is displayed.

4. To edit the draft, click Edit draft.

   1. Click the Design tab, and edit the draft.
   2. (Optional) To see the changes that you made since the last save, click Actions > Show draft changes.
   3. (Optional) In the left pane of the draft editor, you can add the following items:
   4. Click Save.
   5. Use the breadcrumbs to navigate back to the Drafts page.

Procedure

1. Navigate to the draft in Apicurio Studio. For example:

   1. Set Filter by to Name
   2. Enter the name of the draft in the search field.
   3. Click the Search icon or press Return.

2. You can finalize a draft in two ways:

   • From the search results, click the options icon (three vertical dots) and choose Finalize draft.
   • Click on the draft coordinates listed in the search results to see the draft details page and then click the Finalize draft button.

   The Final draft? modal is displayed.

3. Confirm that you want to finalize the draft.

   A Dry run only option allows you to validate the draft before finalizing it.

   A confirmation page appears with the details of the artifact.

   Important

   After a draft is finalized, you can no longer view or edit that artifact in Apicurio Studio. You must use Apicurio Registry to perform further edits.

4. Navigate to the artifact in Apicurio Registry. From the confirmation page, you can navigate to the artifact in Apicurio Registry by selecting View in Registry from the options menu (three vertical dots).