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 } = 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",
);

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

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

Swagger

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

Hydra

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

GraphQL

function parseGraphQl(
  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.

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

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

For Hydra resources, getParameters() loads parameters lazily and caches the result for the lifetime of the Resource instance. Run the documentation parser again to refresh parameters after the API schema or authorization context changes.

Field

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

Parameter

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

FieldType

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;

Operation

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

📖 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 same Review 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.