Skip to content

Latest commit

 

History

History

getting-started-api-designer

Folders and files

NameName
Last commit message
Last commit date

parent directory

..

images

images

 
 

README.adoc

README.adoc

 
 

quickstart.yml

quickstart.yml

 
 

README.adoc

Getting started with OpenShift API Designer

As an API owner or developer, you can use OpenShift API Designer to design event schemas and API definitions that comply with vendor-neutral and portable open specifications. OpenShift API Designer is a managed cloud service that enables you to design schemas and API definitions without having to install, configure, run, and maintain your own API Designer infrastructure.

For more overview information, see the OpenShift API Designer user documentation.

Creating an API design

Use the OpenShift API Designer web console to create an OpenAPI or AsyncAPI definition.

Prerequisites
Procedure

  1. In the OpenShift API Designer 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.

    Note
    		 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 OpenShift Service Registry, download the design to a file, or delete the design.

Verification

  1. Verify that the new design is listed on the designs page.

  2. Verify that the design details are correct.

Creating a schema design

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

Prerequisites
Procedure

  1. In the OpenShift API Designer 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 OpenShift Service Registry, download the design to a file, or delete the design.

Verification

  1. Verify that the new design is listed on the designs page.

  2. Verify that the design details are correct.

Importing a schema or API design

You can import an event schema or API definition into OpenShift API Designer from a URL, from a file, or from a running OpenShift Service Registry instance.

Prerequisites
Procedure

  1. In the OpenShift API Designer web console, click Import design, and then click one of the following options:

    • Import from Service Registry: From the instances list, select a Service Registry instance. Browse the list of artifacts for that instance, and select an artifact.

    • 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 Service 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.

Verification

  1. Verify that the imported design is listed on the designs page.

  2. Verify that the design details are correct.

Testing a schema or API design

You can test that your schema or API design content is valid and compatible with existing content by applying the rules of an existing OpenShift Service Registry instance. You can test the design while working in the OpenShift API Designer editor, without exporting the design to OpenShift Service Registry.

Prerequisites
Procedure

  1. On the API and Schema Designs page of the OpenShift API Designer web console, select the design that you want to test.

  2. Click the options icon (three vertical dots), and click Edit design content to open the design editor.

  3. From the Actions menu, click Run Service Registry check.

  4. From the Registry instance list, select a Service Registry instance.

  5. In the Group and ID fields, specify the artifact details.

  6. Click Test.

A new pane in the design editor window shows the registration issues found by the test:

  • If the design content obeys the specified rules, the registration issues pane contains the following text: Registry Test completed with no issues

  • If the registration issues pane provides details of any issues, resolve the issues and click Retry to retest the content using the same artifact rules.

Verification

  1. Verify that the registration issues pane is shown in the design editor.

  2. Verify that the test results are correct.

Exporting a schema or API design

When you’re happy with the changes to your OpenShift API Designer event schema or API definition, and you want to use the design in your application, you can export the content to an existing OpenShift Service Registry instance.

Prerequisites
Procedure

  1. On the API and Schema Designs page of the OpenShift API Designer web console, select the design that you want to export.

  2. Click the options icon (three vertical dots), and click Export design to Service Registry.

    Note
    		 You can also select Export design to Service Registry from the Actions menu in the design editor.

  3. Complete the form to specify where to save the new design. Provide the following details:

    Note
    		 If the design was originally imported from OpenShift Service Registry, the fields are prepopulated with the details of the original Service Registry instance, and the Version field is blank.

    • Registry Instance: Select the required instance from the list.

    • Group (Optional): Enter a unique group name such as my-org to organize the artifact in a named collection. Each group contains a logically related set of schemas or API designs, typically managed by a single entity, belonging to a particular application or organization.

      Note
      		 Specifying a group is optional when using the web console. If no group is specified, Service Registry uses the default group.

    • ID (Optional): Enter a unique ID for this artifact, such as my-ID. If you don’t specify a unique artifact ID, Service Registry generates one automatically as a UUID.

    • Version (Optional): Specify the version number. If you don’t specify a version number, Service Registry sets the version to 1 for the first version, or increments the latest version by 1 for subsequent versions.

  4. Click Export. The exported design is listed on the artifacts page of the specified Service Registry instance.

You can use OpenShift Service Registry to manage the versions of a design from OpenShift API Designer. You can also download a design from API Designer to a file, either for local client code generation or to import the design into OpenShift API Management.

Verification

  • Verify that the design is listed as an artifact in OpenShift Service Registry.

  • Verify that the artifact details are correct.