+
# API Doc Parser
-[](https://github.com/api-platform/api-doc-parser/actions?query=workflow%3ACI+branch%3Amain)
+**Effortlessly turn Hydra, Swagger/OpenAPI, and GraphQL specs into actionable data for your tools and apps.**
+
+[](https://github.com/api-platform/api-doc-parser/actions/workflows/ci.yml)
+[](https://github.com/api-platform/api-doc-parser/blob/main/LICENSE)
+[](https://bundlephobia.com/package/@api-platform/api-doc-parser)
[](https://badge.fury.io/js/%40api-platform%2Fapi-doc-parser)
+[](https://img.shields.io/npm/dw/%40api-platform%2Fapi-doc-parser)
-`api-doc-parser` is a standalone TypeScript library to parse [Hydra](http://hydra-cg.com), [Swagger](https://swagger.io/specification/v2/), [OpenAPI](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification) and [GraphQL](https://graphql.org/) documentations
-and transform them in an intermediate representation.
-This data structure can then be used for various tasks such as creating smart API clients,
-scaffolding code or building administration interfaces.
+---
-It plays well with the [API Platform](https://api-platform.com) framework.
+**`api-doc-parser` is a standalone TypeScript library that parses [Hydra](https://www.hydra-cg.com/), [Swagger](https://swagger.io/specification/v2/), [OpenAPI](https://github.com/OAI/OpenAPI-Specification#the-openapi-specification), and [GraphQL](https://graphql.org/) 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](https://api-platform.com/) framework.
-## Install
+## ✨ Key Features
-With [Yarn](https://yarnpkg.com/):
+- **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
- yarn add @api-platform/api-doc-parser
+## 📦 Installation
Using [NPM](https://www.npmjs.com/):
@@ -24,19 +40,23 @@ Using [Pnpm](https://pnpm.io/):
pnpm add @api-platform/api-doc-parser
-If you plan to use the library with Node, you also need a polyfill for the `fetch` function:
+With [Yarn](https://yarnpkg.com/):
+
+ yarn add @api-platform/api-doc-parser
+
+Using [Bun](https://bun.sh/):
- yarn add isomorphic-fetch
+ bun add @api-platform/api-doc-parser
-## Usage
+## 🚀 Usage
**Hydra**
```javascript
import { parseHydraDocumentation } from "@api-platform/api-doc-parser";
-parseHydraDocumentation("https://demo.api-platform.com").then(({ api }) =>
- console.log(api),
+const { api, response, status } = await parseHydraDocumentation(
+ "https://demo.api-platform.com",
);
```
@@ -45,8 +65,8 @@ parseHydraDocumentation("https://demo.api-platform.com").then(({ api }) =>
```javascript
import { parseSwaggerDocumentation } from "@api-platform/api-doc-parser";
-parseSwaggerDocumentation("https://demo.api-platform.com/docs.json").then(
- ({ api }) => console.log(api),
+const { api, response, status } = await parseSwaggerDocumentation(
+ "https://demo.api-platform.com/docs.json",
);
```
@@ -55,9 +75,9 @@ parseSwaggerDocumentation("https://demo.api-platform.com/docs.json").then(
```javascript
import { parseOpenApi3Documentation } from "@api-platform/api-doc-parser";
-parseOpenApi3Documentation(
- "https://demo.api-platform.com/docs.json?spec_version=3",
-).then(({ api }) => console.log(api));
+const { api, response, status } = await parseOpenApi3Documentation(
+ "https://demo.api-platform.com/docs.jsonopenapi?spec_version=3.0.0",
+);
```
**GraphQL**
@@ -65,42 +85,266 @@ parseOpenApi3Documentation(
```javascript
import { parseGraphQl } from "@api-platform/api-doc-parser";
-parseGraphQl("https://demo.api-platform.com/graphql").then(({ api }) =>
- console.log(api),
+const { api, response } = await parseGraphQl(
+ "https://demo.api-platform.com/graphql",
);
```
-## OpenAPI Support
+##  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:
-In order to support OpenAPI, the library makes some assumptions about how the documentation relates to a corresponding ressource:
+#### OpenAPI 3
+
+```typescript
+function parseOpenApi3Documentation(
+ entrypointUrl: string,
+ options?: RequestInitExtended,
+): Promise<{
+ api: Api;
+ response: OpenAPIV3.Document;
+ status: number;
+}>;
+```
-- The path to get (`GET`) or edit (`PUT`) one resource looks like `/books/{id}` (regular expression used: `^[^{}]+/{[^{}]+}/?$`).
- Note that `books` may be a singular noun (`book`).
- If there is no path like this, the library skips the resource.
-- The corresponding path schema is retrieved for `get` either in the [`response` / `200` / `content` / `application/json`] path section or in the `components` section of the documentation.
- If retrieved from the `components` section, the component name needs to look like `Book` (singular noun).
- For `put`, the schema is only retrieved in the [`requestBody` / `content` / `application/json`] path section.
- If no schema is found, the resource is skipped.
-- If there are two schemas (one for `get` and one for `put`), resource fields are merged.
-- The library looks for a creation (`POST`) and list (`GET`) path. They need to look like `/books` (plural noun).
-- The deletion (`DELETE`) path needs to be inside the get / edit path.
-- In order to reference the resources between themselves (embeddeds or relations), the library guesses embeddeds or references from property names.
- For instance if a book schema has a `reviews` property, the library tries to find a `Review` resource.
- If there is, a relation or an embedded between `Book` and `Review` resources is made for the `reviews` field.
- The property name can also be like `review_id`, `reviewId`, `review_ids` or `reviewIds` for references.
-- Parameters are only retrieved in the list path.
+#### Swagger
-## Support for other formats (JSON:API...)
+```typescript
+function parseSwaggerDocumentation(entrypointUrl: string): Promise<{
+ api: Api;
+ response: OpenAPIV2.Document;
+ status: number;
+}>;
+```
+
+#### Hydra
+
+```typescript
+function parseHydraDocumentation(
+ entrypointUrl: string,
+ options?: RequestInitExtended,
+): Promise<{
+ api: Api;
+ response: Response;
+ status: number;
+}>;
+```
+
+#### GraphQL
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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 | null;
+ operations?: Operation[] | null;
+}
+```
+
+### Field
+
+Represents a property of a resource, including its type, constraints, and metadata.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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](https://github.com/api-platform/api-doc-parser/pulls)
to include it in the library.
-## Run tests
+## 🤝 Contributing
+
+Contributions are welcome! To contribute:
+
+1. **Read our [Code of Conduct](https://github.com/api-platform/api-doc-parser?tab=coc-ov-file#contributor-code-of-conduct).**
+
+2. **Fork the repository and create a feature branch.**
+
+3. **Install dependencies**
- pnpm test
- pnpm lint
+ ```bash
+ pnpm install
+ ```
-## Credits
+4. **Adhere to the code style**
+
+ ```bash
+ pnpm lint:fix
+ ```
+
+ ```bash
+ pnpm format
+ ```
+
+5. **Run tests**
+
+ ```bash
+ pnpm test
+ ```
+
+6. **Ensure type correctness**
+
+ ```bash
+ pnpm typecheck
+ ```
+
+7. **Submit a pull request with a clear description of your changes.**
+
+## 👥 Contributors
+
+[](https://github.com/api-platform/api-doc-parser/graphs/contributors)
+
+## 🌟 Star History
+
+
+
+
+
+
+
+
+
+## 🙌 Credits
Created by [Kévin Dunglas](https://dunglas.fr). Sponsored by [Les-Tilleuls.coop](https://les-tilleuls.coop).
+
+## 🔒 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.