Overview: API Designer - AI-Assisted with Agent Design Expert

The API Designer in ApiShare provides a dedicated environment for creating and managing OpenAPI specifications. It is designed to support the entire API design process, allowing users to define, validate, and test API definitions before they are published or integrated into the customer’s API ecosystem.

Through the Designer, users can work on API specifications in a structured workspace that supports both manual editing and guided configuration, ensuring flexibility for users with different levels of familiarity with the OpenAPI standard. Additionally, the Designer leverages our Agent Design Expert, an AI-assisted tool that enhances the design experience by providing intelligent suggestions and automating parts of the design process.

The Designer allows users to perform the following activities:

• View complete OpenAPI specifications

• Create new OpenAPI specifications from scratch

• Modify and correct existing OpenAPI specifications (by uploading an existing one, or starting from a template)

• Validate specifications against the OpenAPI standard or internal rules

• Test API endpoints directly from the interface

• Save specifications locally for reuse or version control

Editing an OpenAPI Specification

The Designer supports two alternative ways to work with OpenAPI specifications. Both modes operate on the same underlying specification and can be used interchangeably.

Form View

he Form View provides a guided interface for working with OpenAPI specifications through structured fields. Instead of editing the raw specification, users interact with form-based components that automatically generate the underlying OpenAPI structure.

Key characteristics include:

• Structured forms for defining API elements

• Simplified creation of paths, operations, and parameters

• Guided input to reduce syntax errors

• Automatic generation of the underlying specification

This mode is particularly useful for users who prefer a visual and guided approach to API design.

Main Form Sections and Features

The form sections on the left reflect the broader objects or sections of the OpenAPI Specification schema. They are the following:

• INFO: The Info section provides metadata about the API.

• TAGS: This section adds Tags that can be used for each method within each path defined for the specification. These tags can help categorize paths and methods.

• SERVERS: This section defines the Servers from which the endpoints will be reached. You can define multiple servers, usually for each machine or environment that exposes the API.

• PATHS: In the Paths section the user can be guided in defining all the necessary details of each enpdpoint and each method (GET, POST, PUT, …), including references to the data structures (schemas), parameters, requests, responses (200, 400, …), and examples.

• SECURITY: This section allows the user to select which security schemes apply globally to this API. (To select items here they should be first created from dedicated Components section.)

• COMPONENTS: The Components section is further divided in Examples, Headers, Parameters, Request Bodies, Responses, Schemas, and Security Schemes. These are the subsections that, in general, determine the information that can be centralized and reused in the former sections.

A particular focus deserves the Schemas section wherein users can define all reusable data structures via a guided form without working directly on the raw JSON or YAML. Users can add properties, specify their type and metadata, define nested items or child structures visualizing them in a Tree view. More expert users can always see the schemas as JSON or YAML without moving to the code view.

Code View

The Code View allows users to edit the OpenAPI specification directly in its source format (YAML or JSON). This mode is typically used by developers who prefer working directly with the specification syntax and need full control over the structure of the API definition.

Key characteristics include:

• Direct editing of the OpenAPI document

• Syntax highlighting for improved readability

• Full control over the specification structure

• Immediate validation feedback when errors are detected

This approach provides maximum flexibility and is particularly suitable for advanced users familiar with the OpenAPI specification format.

If fields or parameters are added in Code View that are not syntactically valid (an therefore cannot be interpreted in Form View), they will be removed once you switch views, except for those classified as extensions (x-). Make sure any edits made in code view are syntactically valid before switching back to the Form View.

Loading templates

Aside from uploading existing specifications, the Designer allows the user to begin from pre-existing OpenaAPI specification templates. These templates che be pre-loaded on ApiShare and can be inclusive of all common boiler-plate definitions, schemas, tags, etc. that are common withing your company’s API specifications.

Starting from a template allows designers of APIs to skip filling in repeated and common information in the OpenAPI Specs, which in turn allows companies and teams to produce consistent and compliant APIs with ease.

NOTE: When a template is loaded, any existing changes are replaced. Make sure you have saved or downloaded any previous work on the API Designer.

Validation and Preview

The Designer includes built-in validation and preview capabilities that help ensure API specifications are correct, and compliant with company guidelines before being published.

Validation features allow users to check the specification against:

• the OpenAPI standard

• internal guidelines and rules or platform constraints: ApiShare can be enabled to check against a set of configurable available validation rule (defined by and validated with Spectral), as well as custom ones, specific to your enterprise’s requirements.

The preview capability enables users to execute API requests directly from the Designer interface, allowing quick verification of endpoints and parameters (assuming a back-end is already available). This helps detect issues early in the design phase and ensures that APIs are properly defined before entering the lifecycle management process.

AI Assistance

If the ApiShare Design Expert is enabled, the ApiShare AI Design Agent will be available within the Designer to assist users during the API design process.

The AI Design Agent can support and automate several of the activities described in this section, including specification creation (supporting also file uploads for input), validation against company guidelines, correction, and refinement. By analyzing the structure and content of the OpenAPI document, it helps streamline the design workflow and reduce manual effort.

When creating a OpenAPI Specification, the AI Assistant, starting from the prompt as well as any attached documents, shall generate a first draft of the specification which will then need to be accepted or rejected via the buttons below. This will also occur when the AI Assistant is asked to edit or fix validation errors in the existing OpenAPI specification, according to your enterprise validation rulesets. Preview the changes of the AI Assistant can only be done via Code View, which will also allow specific edits before the changes are accepted.

Saving and Reusing Specifications

API specifications created in the Designer can be saved locally and reused as the basis for future APIs.

This allows teams to:

• maintain local copies of their API definitions

• reuse templates for similar APIs

• iterate on specifications before publishing APIs represented by those specifications from ApiShare

By combining editing, validation, and testing capabilities in a single workspace, the Designer simplifies the API design workflow and helps ensure that API specifications are accurate, consistent across teams, and ready for lifecycle management within the platform.