api-platform/api-doc-parserPublic

NotificationsYou must be signed in to change notification settings
Fork77
Star110

Transforms a Hydra API doc in an intermediate representation that can be used for various tasks such as creating smart API clients, scaffolding code or building administration interfaces.

License

MIT license

110 stars 77 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 283 Commits
.github/workflows		.github/workflows
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.oxlintrc.json		.oxlintrc.json
.prettierignore		.prettierignore
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts

Repository files navigation

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 parsesHydra,Swagger,OpenAPI, andGraphQL documentation into a unified, intermediate representation.
This normalized structure enables smart API clients, code generators, admin interfaces, and more.
It integrates seamlessly with theAPI Platform framework.

✨ Key Features

Unified output – one normalizedApi 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

UsingNPM:

npm install @api-platform/api-doc-parser

UsingPnpm:

pnpm add @api-platform/api-doc-parser

WithYarn:

yarn add @api-platform/api-doc-parser

UsingBun:

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) endpointmust 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 aremerged.
Collection paths	A create (`POST`) or list (`GET`) endpointmust 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`) becomeembedded 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 asreferences to that resource. • As a result, fields such as`reviews` (object/array) and`review_ids` (scalar/array of IDs) each point to thesame`Review` resource, one flaggedembedded, the otherreference.
Parameter extraction	Parameters are readonly 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, pleaseopen a Pull Requestto include it in the library.

🤝 Contributing

Contributions are welcome! To contribute:

Read ourCode of Conduct.
Fork the repository and create a feature branch.
Ensure you have thelatest version ofpnpm installed.
Install dependencies
```
pnpm install
```
Adhere to the code style and lint rules
```
pnpm lint:fix
```
```
pnpm format
```
Run tests
```
pnpmtest
```
Ensure type correctness
```
pnpm typecheck
```
Submit a pull request with a clear description of your changes.

👥 Contributors

🌟 Star History

🙌 Credits

Created byKévin Dunglas. Sponsored byLes-Tilleuls.coop.

🔒 License

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

About

Transforms a Hydra API doc in an intermediate representation that can be used for various tasks such as creating smart API clients, scaffolding code or building administration interfaces.