API Doc Parser

Effortlessly 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.

✨ Key Features

• 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

📦 Installation

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

🚀 Usage

Hydra

import{parseHydraDocumentation}from"@api-platform/api-doc-parser";const{ api, response, status }=awaitparseHydraDocumentation("https://demo.api-platform.com",);

OpenAPI v2 (formerly known as Swagger)

import{parseSwaggerDocumentation}from"@api-platform/api-doc-parser";const{ api, response, status }=awaitparseSwaggerDocumentation("https://demo.api-platform.com/docs.json",);

OpenAPI v3

import{parseOpenApi3Documentation}from"@api-platform/api-doc-parser";const{ api, response, status }=awaitparseOpenApi3Documentation("https://demo.api-platform.com/docs.jsonopenapi?spec_version=3.0.0",);

GraphQL

import{parseGraphQl}from"@api-platform/api-doc-parser";const{ api, response }=awaitparseGraphQl("https://demo.api-platform.com/graphql",);

Type definitions

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

functionparseOpenApi3Documentation(entrypointUrl: string,options?: RequestInitExtended,): Promise<{api: Api;response: OpenAPIV3.Document;status: number;}>;

Swagger

functionparseSwaggerDocumentation(entrypointUrl: string): Promise<{api: Api;response: OpenAPIV2.Document;status: number;}>;

Hydra

functionparseHydraDocumentation(entrypointUrl: string,options?: RequestInitExtended,): Promise<{api: Api;response: Response;status: number;}>;

GraphQL

functionparseGraphQl(entrypointUrl: string,options?: RequestInit,): Promise<{api: Api;response: Response;}>;

Api

Represents the root of the parsed API, containing the entrypoint URL, an optional title, and a list of resources.

interfaceApi{entrypoint: string;title?: string;resources?: Resource[];}

Resource

Describes an API resource (such as an entity or collection), including its fields, operations, and metadata.

interfaceResource{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<Parameter[]>|null;operations?: Operation[]|null;}

Field

Represents a property of a resource, including its type, constraints, and metadata.

interfaceField{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;}

Parameter

Represents a query parameter for a collection/list operation, such as a filter or pagination variable.

interfaceParameter{variable: string;range: string|null;required: boolean;description: string;deprecated?: boolean;}

FieldType

Enumerates the possible types for a field, such as string, integer, date, etc.

typeFieldType=|"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;

Operation

Represents an operation (such as GET, POST, PUT, PATCH, DELETE) that can be performed on a resource.

interfaceOperation{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;}

📖 OpenAPI Support

api-doc-parser applies a predictable set of rules when interpreting an OpenAPI document.
If a rule is not met, the resource concerned is silently skipped.

Rule	Details
Single-item path pattern	A GET (read) or PUT/PATCH (update) endpoint must match: /books/{id} (regex ^[^{}]+/{[^{}]+}/?$). books may be singular (/book/{id}).
Schema discovery	GET → first searches responses → 200 → content → application/json; if missing, falls back to components (component name must be singular, e.g. Book). PUT/PATCH → only requestBody → content → application/json is considered. If both GET & PUT/PATCH schemas exist, their fields are merged.
Collection paths	A create (POST) or list (GET) endpoint must be plural: /books.
Deletion path	DELETE must live under the single-item GET path (/books/{id}).
Relations & Embeddeds	Links between resources are inferred from property names and their JSON schema: • Plural object/array properties (e.g. reviews, authors) become embedded resources when their item schema matches an existing resource (Review, Author). • ID-like properties (e.g. review_id, reviewId, review_ids, reviewIds, authorId) are treated as references to that resource. • As a result, fields such as reviews (object/array) and review_ids (scalar/array of IDs) each point to the sameReview resource, one flagged embedded, the other reference.
Parameter extraction	Parameters are read only from the list path (/books).

🧩 Support for other formats (JSON:API, AsyncAPI...)

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.

🤝 Contributing

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

   pnpm install

5. Adhere to the code style and lint rules

   pnpm lint:fix

   pnpm format

6. Run tests

   pnpm test

7. Ensure type correctness

   pnpm typecheck

8. Submit a pull request with a clear description of your changes.

👥 Contributors

🌟 Star History

🙌 Credits

Created by Kévin Dunglas. Sponsored by Les-Tilleuls.coop.

🔒 License

This project is licensed under the MIT License - see the LICENSE file for details.