You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
`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
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.
| **Single-item path pattern** | A `GET` (read) or **`PUT`/`PATCH`** (update) endpoint **must** match:<br/>`/books/{id}` (regex `^[^{}]+/{[^{}]+}/?$`).<br/>`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`).<br/>**PUT/PATCH** β only `requestBody β content β application/json` is considered.<br/>If both GET & PUT/PATCH schemas exist, their fields are **merged**. |
| **Collection paths** | A create (`POST`) or list (`GET`) endpoint **must** be plural:<br/>`/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:<br/>β’ **Plural object/array properties** (e.g. `reviews`, `authors`) become **embedded** resources when their item schema matches an existing resource (`Review`, `Author`).<br/>β’ **ID-like properties** (e.g. `review_id`, `reviewId`, `review_ids`, `reviewIds`, `authorId`) are treated as **references** to that resource.<br/>β’ 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`). |
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.