README.md

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

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.