# Can I Use OpenAPI Specifications for Claude Plugins? The Complete Developer Guide

> Learn how to use OpenAPI specifications for Claude plugins. This guide shows developers how to automatically generate tool schemas with the OpenAPI Parser skill for seamless integration.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Yes, Claude plugins can consume OpenAPI specifications to automatically generate tool schemas using the OpenAPI Parser skill available in the community marketplace.**

The `anthropics/claude-plugins-community` repository provides native support for OpenAPI 3.x documents through a dedicated parser skill. This capability eliminates manual tool definition and lets you expose any REST API to Claude Code with minimal configuration.

## How OpenAPI Support Works in Claude Plugins

The OpenAPI Parser skill transforms standard API specifications into native Claude Code tools. According to the `anthropics/claude-plugins-community` source code, this skill parses complex OpenAPI constructs—including `anyOf/oneOf/allOf`, `$ref` chains, discriminators, enums, and regex patterns—and produces executable tool descriptors.

The workflow follows three stages:

1. **Plugin manifest configuration** – Define your plugin in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) with required user settings like API keys.
2. **OpenAPI Parser invocation** – Call the `/openapi-parse` command with your spec URL or file.
3. **Runtime tool injection** – Generated tools become available for natural-language API interaction.

The skill is implemented as a standalone marketplace entry that any plugin can reference, following the standard Claude Plugin architecture documented in the repository root.

## Setting Up a Plugin with OpenAPI Specifications

### Required Plugin Structure

Every Claude plugin using OpenAPI specs requires a `.claude-plugin` directory containing [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). The OpenAPI Parser skill is declared in the `skills` array, as shown in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) at lines 19502-19526.

### Minimal Plugin Manifest Example

```json
{
  "name": "sample-openapi-plugin",
  "description": "Demo plugin that loads an OpenAPI spec and generates Claude tools.",
  "version": "0.1.0",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "homepage": "https://github.com/your/sample-openapi-plugin",
  "license": "MIT",
  "userConfig": {
    "API_KEY": {
      "title": "API Key",
      "description": "Key for the target API",
      "type": "string",
      "sensitive": true
    }
  },
  "skills": [
    {
      "name": "openapi-parse",
      "source": {
        "source": "url",
        "url": "https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json",
        "sha": "latest"
      },
      "description": "Parse an OpenAPI spec and generate Claude tools"
    }
  ]
}

```

This manifest demonstrates how **authentication fields** from your OpenAPI spec's `securitySchemes` map to plugin `userConfig` entries, enabling secure credential management without hardcoding.

## Using OpenAPI-Generated Tools in Claude Code

Once configured, the OpenAPI Parser skill exposes a `/openapi-parse` command that accepts raw JSON/YAML files or URLs.

### Loading an OpenAPI Specification

```text
User: Load the OpenAPI spec at https://api.example.com/openapi.yaml
Claude: /openapi-parse https://api.example.com/openapi.yaml

```

Claude responds with generated tools such as `listCustomers`, `createInvoice`, or equivalent endpoints derived from your spec's operation definitions.

### Executing Generated Tools

```text
User: Show me the last five invoices
Claude: /listInvoices limit=5

```

The natural-language prompt maps to the underlying REST call—`/invoices?limit=5` in this example—without requiring users to know the endpoint structure.

## Advanced OpenAPI Features Supported

The OpenAPI Parser skill handles production-grade specifications through comprehensive schema support:

- **Complex type composition**: `anyOf`, `oneOf`, `allOf` constructs resolve to accurate tool parameter types.
- **Reference resolution**: `$ref` chains across multiple files are flattened automatically.
- **Discriminator mappings**: Polymorphic schemas preserve type safety in generated tools.
- **Validation constraints**: Enums, regex patterns, and numeric ranges become Claude-native parameter constraints.

This ensures Claude's LLM receives precise type information for reliable reasoning about API operations.

## Authentication and Security

The parser respects OpenAPI 3.x `securitySchemes` and maps them to plugin configuration:

- **API keys**: Stored in `userConfig` with `"sensitive": true` for encryption at rest.
- **OAuth2/OIDC flows**: Credential refresh handled through the plugin runtime.
- **HTTP authentication**: Basic and Bearer schemes automatically configured.

No credentials appear in generated tool definitions—they remain bound to the plugin's secure configuration layer.

## Key Source Files and References

| File | Purpose |
|------|---------|
| `.claude-plugin/marketplace.json#L19502-L19526` | OpenAPI Parser skill definition and usage documentation |
| [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) | Production example of OpenAPI-integrated plugin structure |
| [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) | Repository-wide plugin development guidelines |

These paths from `anthropics/claude-plugins-community` provide authoritative implementation details for developers building OpenAPI-powered plugins.

## Summary

- **OpenAPI specifications are fully supported** for Claude plugins via the community OpenAPI Parser skill.
- **Automatic tool generation** eliminates manual schema writing for REST API integration.
- **Comprehensive OpenAPI 3.x support** includes advanced constructs like polymorphism and references.
- **Secure authentication mapping** connects spec-defined security to plugin configuration.
- **Natural-language execution** lets users interact with APIs through conversational prompts.

## Frequently Asked Questions

### What OpenAPI versions does the parser support?

The OpenAPI Parser skill supports OpenAPI 3.x specifications. This includes 3.0.x and 3.1.x releases with full feature parity for complex schemas, authentication schemes, and external references.

### Do I need to write tool definitions manually when using an OpenAPI spec?

No. The parser automatically generates tool schemas from your OpenAPI document. You only need to declare the skill in your plugin manifest and invoke `/openapi-parse` with your specification source.

### Where is the OpenAPI Parser skill documented in the repository?

The skill is documented in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) at lines 19502-19526. This entry describes the parser's behavior, command syntax, and integration requirements for plugin developers.

### Can the parser handle specifications split across multiple files?

Yes. The parser resolves `$ref` chains across file boundaries, flattening external references into self-contained tool definitions. This works with both local file sets and remote URL-based specifications.