Getting started with Apicurio Studio

As an API owner or developer, you can use Apicurio Studio to design event schemas and API definitions that comply with vendor-neutral and portable open specifications.

In this quick start, you’ll learn how to create an API definition or event schema from a simple or detailed template, import an existing design to edit it, test a design against rules configured in Apicurio Registry, and export a finished design to Apicurio Registry.

Prerequisites

Creating an API design

Use the Apicurio Studio web console to create an OpenAPI or AsyncAPI definition.

Prerequisites

  • You’re logged in to the Apicurio Studio web console.

Procedure

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

  2. Complete the form to provide the following details for the new design:

    • Name: Enter a unique design name, such as My API Design.

    • Description (Optional): Enter a short description of the design.

    • Type: Accept the default value OpenAPI, or select another API type from the list.

    • Version (OpenAPI only): Accept the default value 3.0.2, or select another version from the list.

    • Template: Select the Pet Store Example template, or select another template from the list.

  3. Click Create. The new API design opens in the design editor.

  4. Select the design title and click the pen icon. Change the design title to Orders and click the Save changes icon.

    Editing the design title does not change the design name. To rename a design, click Actions > Edit design metadata, edit the design name, and click Save.

  5. Click the Design tab, and optionally edit the design 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.

  6. Click the Source tab, and review the live preview of the design. The content of the Source tab automatically updates when you edit values on the editor page.

  7. (Optional) To see the changes that you made since the last save, click Actions > Show design changes.

  8. (Optional) In the left pane of the design 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

  9. Click Save.

    The new design is listed on the API and Schema Designs page. You can use the options icon (three vertical dots) to view or edit the design details, edit the design content, export the design to Apicurio Registry, download the design to a file, or delete the design.

Creating a schema design

Use the Apicurio Studio web console to create an Apache Avro, JSON Schema, or Google Protocol Buffers (Protobuf) event schema.

Prerequisites

  • You’re logged in to the Apicurio Studio web console.

Procedure

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

  2. Complete the form to provide the following details for the new design:

    • Name: Enter a unique design name, such as My Schema Design.

    • Description (Optional): Enter a short description of the design.

    • Type: From the list, select Apache Avro, or select another schema type.

  3. Click Create. The new schema design opens in the design editor.

  4. Edit the design source to provide your content.

  5. (Optional) To see the changes that you made since the last save, click Actions > Show design changes.

  6. (Optional) For Apache Avro or JSON Schema designs, you can click Actions > Format design content to insert spaces and tabs that align your design content correctly.

  7. Click Save.

    The new design is listed on the API and Schema Designs page. You can use the options icon (three vertical dots) to view or edit the design details, edit the design content, export the design to Apicurio Registry, download the design to a file, or delete the design.

Importing a schema or API design

You can import an event schema or API definition into Apicurio Studio from a URL, from a file, or from a running Apicurio Registry instance.

Prerequisites

  • You’re logged in to the Apicurio Studio web console.

  • You can access a running Apicurio Registry instance in your organization, if you want to import from Apicurio Registry. For more information, see Introduction to Apicurio Registry.

Procedure

  1. In the Apicurio Studio web console, click Import design, and then click one of the following options:

    • Import from URL: Enter a valid and accessible URL, and click Fetch.

    • Import from file: Click Browse and select a file, or drag and drop a file.

  2. When prompted, provide additional information such as version (OpenAPI only), name, type, and description in the import dialog. You can overwrite any autopopulated values.

  3. Click Import. The design editor opens automatically.

When you finish editing, you can export the updated design to Apicurio Registry as a new artifact or as a new version of the existing artifact. You can export the design from the design editor or from the API and Schema Designs page. You can also save your changes locally, or download the content to a file.

Additional resources