Generate OpenAPI Specification with API Design Agent

You can rapidly design APIs and generate comprehensive OpenAPI specifications with the API Design Agent. The API Design Agent is an AI-driven tool that leverages natural language descriptions to generate a deployment-ready 3.1.0 OpenAPI specification.

Generate OpenAPI Specification

1. In API Control Plane, select APIs > Actions.

2. Select Generate OpenAPI Specification.

3. Populate the following mandatory fields.

   note

   Each field must contain between 10 and 5000 characters.

   • Technical Name - The technical API name.
   • Display Name - The API display name.
   • Status - If active, the API can be subscribed to and is visible in the Developer Portal.
   • Owner - The organization the API belongs to.
   • API Purpose - The business problem the API solves or key domains it manages.
   • API Consumers - The primary users or consumers of the API and how they interact.

4. Populate the following optional fields as necessary. Adding more information will produce the most accurate specification.

   note

   Each field is limited to 5000 characters.

   • API Objects/Entities - The main objects or entities that exist in your domain. This helps define the API data models and endpoints.
   • Authentication - The authentication method that ensures the API is secure.
   • Operations - The types of operations users will have with each resource.
   • Key Fields - Key fields/properties for each resource.
   • Retrieval Details - Pagination, filtering, and sorting options.
   • Error Handling - Custom error codes and special error-handling rules.
   • Versioning - Versioning strategy for the API.

5. Select Generate. A time estimate displays as the specification is generated and you are automatically redirected to the new API.

6. When complete, the OpenAPI specification's security and quality scores display. Select View to open the generated specification.

note

If the specification doesn't generate, a message will display with the reason for the failure. Select Try again and you are re-directed to the previous page.

Generate Open Proxy Specification

To deploy your API, you must create an Open Proxy Specification. The Open Proxy Specification is used to describe the publishing of an API in a vendor agnostic way. Environments supporting this capability are able to transform this vendor agnostic spec into the format used by the runtime and deploy it on the runtime. This can be used to create and update API proxies in a unified way across multiple runtimes.

1. Open APIs and select your API name.
2. Select Versions and select the API version from the list.
3. Select Open Proxy Specification.
4. Select Generate Open Proxy Specification.
5. Provide the following:
   • Backend URL
   • Gateway Context Path
6. Select Create. The Open Proxy file opens.