# Best Practices for Developing an OpenAPI Spec for OpenAI Plugins

> Learn best practices for developing OpenAPI specs for OpenAI plugins. Ensure stable endpoints, centralized authentication, and provide model examples for better reasoning.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-07-12

---

**Develop robust OpenAI plugins by authoring OpenAPI 3.0+ specifications that expose stable endpoints, centralize authentication in `components.securitySchemes`, and include concrete request/response examples to guide the model's reasoning.**

The OpenAPI specification serves as the definitive contract between ChatGPT and your external service, dictating how the model authenticates, routes requests, and parses responses. According to the `openai/plugins` repository, well-structured specs reduce integration bugs and improve latency by allowing the model to reason accurately about available endpoints. Following the patterns established in the Zoom and Cloudflare reference implementations ensures your plugin is discoverable, secure, and maintainable.

## Adopt OpenAPI 3.0 and Semantic Versioning

Use **OpenAPI 3.0** or higher to leverage modern features like reusable components and rich security schemes. The `openai/plugins` repository explicitly recommends this version, as seen in [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md), because it guarantees compatibility with OpenAI's plugin loader and modern code generators.

Always include **semantic versioning** in the `info.version` field to enable graceful API evolution without breaking existing callers. Version tags allow the model to handle gradual feature rollouts and deprecations safely.

## Centralize Authentication with Security Schemes

Define all **authentication mechanisms** once within `components.securitySchemes` and reference them globally via the top-level `security` array. This pattern, illustrated in the Cloudflare Hono examples at [`plugins/cloudflare/skills/cloudflare/references/workers/frameworks.md`](https://github.com/openai/plugins/blob/main/plugins/cloudflare/skills/cloudflare/references/workers/frameworks.md), eliminates duplication across individual paths and ensures ChatGPT applies credentials consistently.

Centralizing tokens, API keys, or OAuth flows reduces the attack surface and simplifies credential rotation when security requirements change.

## Expose the Spec at a Stable, Well-Known URL

Expose the OpenAPI document at a static, versioned endpoint such as **[`/.well-known/openapi.json`](https://github.com/openai/plugins/blob/main//.well-known/openapi.json)** or a dedicated CDN-backed URL. The Zoom reference implementation in [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md) demonstrates hosting specs on high-availability infrastructure like GitHub Pages or Cloudflare Workers to guarantee low-latency access for the model.

Avoid dynamic generation that could alter the schema between requests, as this destabilizes the model's understanding of your API surface.

## Scope Endpoints to Required Functionality

Include **only the paths and operations** necessary for the plugin's capabilities, explicitly omitting internal or administrative endpoints. The repository guidance emphasizes that minimizing the published surface reduces latency and limits security exposure.

By pruning unused CRUD operations from the spec, you provide ChatGPT with a focused, unambiguous contract that improves tool selection accuracy and prevents hallucinated calls to non-existent resources.

## Populate Examples and Error Schemas

Every request parameter and response body should include concrete **`example`** values, and every path should document possible HTTP error codes with corresponding schemas. The Zoom OpenAPI guide shows that explicit examples dramatically improve the model's ability to construct valid payloads.

Documented error codes (401, 404, 429) enable ChatGPT to surface meaningful troubleshooting messages to users. Define error schemas in `components.schemas` and reference them in `responses` to ensure consistency across the API.

## Validate Specs and Generate SDKs Automatically

Integrate **`openapi-validator`** or **`swagger-cli`** into your CI pipeline to catch structural errors before deployment, as implied by the repository's quality gates. Then use **`@openapitools/openapi-generator-cli`** to produce type-safe client SDKs.

The Zoom reference at line 112 of [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md) provides the exact command sequence to generate TypeScript clients, ensuring your plugin implementation stays synchronized with the specification.

### Minimal OpenAPI Document Structure

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "My Awesome Plugin",
    "version": "1.0.0",
    "description": "A simple example plugin that returns a greeting."
  },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/greet": {
      "get": {
        "summary": "Return a greeting",
        "operationId": "greet",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "World" },
            "description": "Name to greet"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful greeting",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Greeting" },
                "example": { "message": "Hello, World!" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Greeting": {
        "type": "object",
        "properties": {
          "message": { "type": "string" }
        },
        "required": ["message"]
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization"
      }
    }
  },
  "security": [{ "apiKeyAuth": [] }]
}

```

### Generating a TypeScript SDK

```bash

# Install the generator CLI globally (as shown in the Zoom reference)

npm install -g @openapitools/openapi-generator-cli

# Generate a TypeScript client from the spec

openapi-generator-cli generate \
  -i https://example.com/.well-known/openapi.json \
  -g typescript-fetch \
  -o ./generated-client

```

## Summary

- Use **OpenAPI 3.0+** with semantic versioning in `info.version` to ensure compatibility.
- Centralize **authentication** definitions in `components.securitySchemes` and reference them globally.
- Host the spec at a **stable URL** like [`/.well-known/openapi.json`](https://github.com/openai/plugins/blob/main//.well-known/openapi.json) with high availability.
- Limit paths to **essential functionality** only to reduce attack surface and latency.
- Include **concrete examples** and **error schemas** for every operation to improve model reasoning.
- **Validate** the spec in CI and **generate type-safe SDKs** with OpenAPI Generator to maintain consistency.

## Frequently Asked Questions

### What OpenAPI version is required for OpenAI plugins?

OpenAPI **3.0 or higher** is required. This version supports the `components` structure, `securitySchemes`, and richer data types that OpenAI's plugin loader expects, as demonstrated in the Zoom reference implementation at [`plugins/zoom/skills/rest-api/references/openapi.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/rest-api/references/openapi.md).

### Where should I host my OpenAPI specification?

Host it at a static, publicly accessible URL such as **[`/.well-known/openapi.json`](https://github.com/openai/plugins/blob/main//.well-known/openapi.json)** or on a CDN like GitHub Pages. The model fetches this document on each invocation, so high availability and low latency are critical for reliable plugin behavior.

### How should I handle API authentication in the OpenAPI spec?

Declare security schemes once in **`components.securitySchemes`** (e.g., `apiKeyAuth` or `oauth2`) and apply them globally via the `security` array. This centralizes credential handling and prevents path-level duplication, following the pattern shown in the Cloudflare Workers reference.

### Should I include every endpoint from my API in the plugin spec?

No. Only expose the specific endpoints required for the plugin's functionality. Minimizing the surface area improves model reasoning latency and reduces security risks by preventing the model from accessing unnecessary internal operations.