Create an OpenAPI Specification

The next component that you need to learn is the OpenAPI Specification.

OpenAPI, also known as Swagger, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.

The OpenAPI Specification provides a standard, language-agnostic interface to RESTful APIs which allows both humans (and now AI models) to discover the capabilities of the service without access to source code, documentation, or through network traffic inspection.

When properly defined via OpenAPI, a consumer (and in this case, ChatGPT) can understand and interact with the remote service with a minimal amount of implementation logic.

Getting Started

To get started, you need to create a OpenAPI specification file. A OpenAPI specification file is a type of file that stores simple objects and data structures in YAML or JSON format.

Let's start with a basic structure using YAML:

openapi: 3.0.0
info:
  title: My ChatGPT Plugin
  version: 1.0.0
paths:

OK. So what's going on here?

Here's what each field means:

• openapi: This field indicates the version of OpenAPI specification you are using.
• info: This section provides metadata about the API such as its title and version.
• paths: This is where you'll describe the endpoints of your API.

Describing Endpoints

Let's say you have an endpoint at /api/my-endpoint. Here's how you describe it:

paths:
  /api/my-endpoint:
    get:
      summary: My endpoint
      responses:
        '200':
          description: Successful operation

In this example:

• /api/my-endpoint is the path of the endpoint.
• get is the HTTP method (could also be post, put, delete, etc.)
• summary is a short summary of what the endpoint does.
• responses describes the responses the endpoint can return.

Adding Parameters

If your endpoint takes parameters, you can describe them like this:

paths:
  /api/my-endpoint:
    get:
      summary: My endpoint
      parameters:
        - in: query
          name: myParameter
          schema:
            type: string
          required: true
          description: My parameter
      responses:
        '200':
          description: Successful operation

In this example, myParameter is a required query parameter of type string.

Conclusion

This guide covers the basics of writing an OpenAPI specification for a ChatGPT plugin. OpenAPI specifications can get much more complex with the addition of request bodies, different response types, and more, but this guide should give you a good starting point.

Once your OpenAPI specification is complete, make sure it's accessible from the URL you specified in your plugin's manifest file (/.well-known/ai-plugin.json). This will allow ChatGPT to understand how to interact with your plugin.

Remember, the key to a good API is clear and comprehensive documentation, and that's exactly what the OpenAPI specification is designed to provide.