Transform an API documentation (Hydra, OpenAPI, GraphQL) in an intermediate representation that can be used for various tasks such as creating smart API clients, scaffolding code or building administration interfaces.
npm install @api-platform/api-doc-parserEffortlessly turn Hydra, Swagger/OpenAPI, and GraphQL specs into actionable data for your tools and apps.





---
api-doc-parser is a standalone TypeScript library that parses Hydra, Swagger, OpenAPI, and GraphQL documentation into a unified, intermediate representation.
This normalized structure enables smart API clients, code generators, admin interfaces, and more.
It integrates seamlessly with the API Platform framework.
- Unified output – one normalized Api object covering resources, fields, operations, parameters, and relations
- TypeScript-first – strict typings for every parsed element
- Embedded & referenced resources resolved automatically
- Framework integration – easily integrates with the API Platform ecosystem
- Supports all major API formats – Hydra, Swagger/OpenAPI v2, OpenAPI v3, and GraphQL
Using NPM:
npm install @api-platform/api-doc-parser
Using Pnpm:
pnpm add @api-platform/api-doc-parser
With Yarn:
yarn add @api-platform/api-doc-parser
Using Bun:
bun add @api-platform/api-doc-parser
Hydra
``javascript
import { parseHydraDocumentation } from "@api-platform/api-doc-parser";
const { api, response, status } = await parseHydraDocumentation(
"https://demo.api-platform.com",
);
`
OpenAPI v2 (formerly known as Swagger)
`javascript
import { parseSwaggerDocumentation } from "@api-platform/api-doc-parser";
const { api, response, status } = await parseSwaggerDocumentation(
"https://demo.api-platform.com/docs.json",
);
`
OpenAPI v3
`javascript
import { parseOpenApi3Documentation } from "@api-platform/api-doc-parser";
const { api, response, status } = await parseOpenApi3Documentation(
"https://demo.api-platform.com/docs.jsonopenapi?spec_version=3.0.0",
);
`
GraphQL
`javascript
import { parseGraphQl } from "@api-platform/api-doc-parser";
const { api, response } = await parseGraphQl(
"https://demo.api-platform.com/graphql",
);
`
Each parse function returns a Promise that resolves to an object containing the normalized API structure, the raw documentation, and the HTTP status code:
#### OpenAPI 3
`typescript`
function parseOpenApi3Documentation(
entrypointUrl: string,
options?: RequestInitExtended,
): Promise<{
api: Api;
response: OpenAPIV3.Document;
status: number;
}>;
#### Swagger
`typescript`
function parseSwaggerDocumentation(entrypointUrl: string): Promise<{
api: Api;
response: OpenAPIV2.Document;
status: number;
}>;
#### Hydra
`typescript`
function parseHydraDocumentation(
entrypointUrl: string,
options?: RequestInitExtended,
): Promise<{
api: Api;
response: Response;
status: number;
}>;
#### GraphQL
`typescript`
function parseGraphQl(
entrypointUrl: string,
options?: RequestInit,
): Promise<{
api: Api;
response: Response;
}>;
Represents the root of the parsed API, containing the entrypoint URL, an optional title, and a list of resources.
`typescript`
interface Api {
entrypoint: string;
title?: string;
resources?: Resource[];
}
Describes an API resource (such as an entity or collection), including its fields, operations, and metadata.
`typescript`
interface Resource {
name: string | null;
url: string | null;
id?: string | null;
title?: string | null;
description?: string | null;
deprecated?: boolean | null;
fields?: Field[] | null;
readableFields?: Field[] | null;
writableFields?: Field[] | null;
parameters?: Parameter[] | null;
getParameters?: () => Promise
operations?: Operation[] | null;
}
Represents a property of a resource, including its type, constraints, and metadata.
`typescript`
interface Field {
name: string | null;
id?: string | null;
range?: string | null;
type?: FieldType | null;
arrayType?: FieldType | null;
enum?: { [key: string | number]: string | number } | null;
reference?: string | Resource | null;
embedded?: Resource | null;
required?: boolean | null;
nullable?: boolean | null;
description?: string | null;
maxCardinality?: number | null;
deprecated?: boolean | null;
}
Represents a query parameter for a collection/list operation, such as a filter or pagination variable.
`typescript`
interface Parameter {
variable: string;
range: string | null;
required: boolean;
description: string;
deprecated?: boolean;
}
Enumerates the possible types for a field, such as string, integer, date, etc.
`typescript`
type FieldType =
| "string"
| "integer"
| "negativeInteger"
| "nonNegativeInteger"
| "positiveInteger"
| "nonPositiveInteger"
| "number"
| "decimal"
| "double"
| "float"
| "boolean"
| "date"
| "dateTime"
| "duration"
| "time"
| "byte"
| "binary"
| "hexBinary"
| "base64Binary"
| "array"
| "object"
| "email"
| "url"
| "uuid"
| "password"
| string;
Represents an operation (such as GET, POST, PUT, PATCH, DELETE) that can be performed on a resource.
`typescript`
interface Operation {
name: string | null;
type: "show" | "edit" | "delete" | "list" | "create" | null;
method?: string | null;
expects?: any | null;
returns?: string | null;
types?: string[] | null;
deprecated?: boolean | null;
}
api-doc-parser applies a predictable set of rules when interpreting an OpenAPI document. GET
If a rule is not met, the resource concerned is silently skipped.
| Rule | Details |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Single-item path pattern | A (read) or PUT/PATCH (update) endpoint must match:/books/{id} (regex ^[^{}]+/{[^{}]+}/?$).books may be singular (/book/{id}). |responses → 200 → content → application/json
| Schema discovery | GET → first searches ; if missing, falls back to components (component name must be singular, e.g. Book).requestBody → content → application/json
PUT/PATCH → only is considered.POST
If both GET & PUT/PATCH schemas exist, their fields are merged. |
| Collection paths | A create () or list (GET) endpoint must be plural:/books. |DELETE
| Deletion path | must live under the single-item GET path (/books/{id}). |reviews
| Relations & Embeddeds | Links between resources are inferred from property names and their JSON schema:
• Plural object/array properties (e.g. , authors) become embedded resources when their item schema matches an existing resource (Review, Author).review_id
• ID-like properties (e.g. , reviewId, review_ids, reviewIds, authorId) are treated as references to that resource.reviews
• As a result, fields such as (object/array) and review_ids (scalar/array of IDs) each point to the same Review resource, one flagged _embedded_, the other _reference_. |/books
| Parameter extraction | Parameters are read only from the list path (). |
API Doc Parser is designed to parse any API documentation format and convert it in the same intermediate representation.
If you develop a parser for another format, please open a Pull Request
to include it in the library.
Contributions are welcome! To contribute:
1. Read our Code of Conduct.
2. Fork the repository and create a feature branch.
3. Ensure you have the _latest_ version of pnpm installed.
4. Install dependencies
`bash`
pnpm install
5. Adhere to the code style and lint rules
`bash`
pnpm lint:fix
`bash`
pnpm format
6. Run tests
`bash`
pnpm test
7. Ensure type correctness
`bash``
pnpm typecheck
8. Submit a pull request with a clear description of your changes.

Created by Kévin Dunglas. Sponsored by Les-Tilleuls.coop.
This project is licensed under the MIT License - see the LICENSE file for details.