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.

• 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

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)

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

OpenAPI v3

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

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:

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

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

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

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.

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

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

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

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

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.

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.

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.

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.
If a rule is not met, the resource concerned is silently skipped.

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

   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.

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

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