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
`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
7
-
and transform them in an intermediate representation.
8
-
This data structure can then be used for various tasks such as creating smart API clients,
9
-
scaffolding code or building administration interfaces.
19
+
---
10
20
11
-
It plays well with the [API Platform](https://api-platform.com) framework.
21
+
**`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.**
22
+
This normalized structure enables smart API clients, code generators, admin interfaces, and more.
23
+
It integrates seamlessly with the [API Platform](https://api-platform.com/) framework.
12
24
13
-
## Install
25
+
## ✨ Key Features
14
26
15
-
With [Yarn](https://yarnpkg.com/):
27
+
-**Unified output** – one normalized `Api` object covering resources, fields, operations, parameters, and relations
28
+
-**TypeScript-first** – strict typings for every parsed element
parseGraphQl("https://demo.api-platform.com/graphql").then(({ api }) =>
69
-
console.log(api),
88
+
const{ api, response } =awaitparseGraphQl(
89
+
"https://demo.api-platform.com/graphql",
70
90
);
71
91
```
72
92
73
-
## OpenAPI Support
93
+
##  Type definitions
94
+
95
+
Each parse function returns a Promise that resolves to an object containing the normalized API structure, the raw documentation, and the HTTP status code:
74
96
75
-
In order to support OpenAPI, the library makes some assumptions about how the documentation relates to a corresponding ressource:
97
+
#### OpenAPI 3
98
+
99
+
```typescript
100
+
function parseOpenApi3Documentation(
101
+
entrypointUrl:string,
102
+
options?:RequestInitExtended,
103
+
):Promise<{
104
+
api:Api;
105
+
response:OpenAPIV3.Document;
106
+
status:number;
107
+
}>;
108
+
```
76
109
77
-
- The path to get (`GET`) or edit (`PUT`) one resource looks like `/books/{id}` (regular expression used: `^[^{}]+/{[^{}]+}/?$`).
78
-
Note that `books` may be a singular noun (`book`).
79
-
If there is no path like this, the library skips the resource.
80
-
- 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.
81
-
If retrieved from the `components` section, the component name needs to look like `Book` (singular noun).
82
-
For `put`, the schema is only retrieved in the [`requestBody` / `content` / `application/json`] path section.
83
-
If no schema is found, the resource is skipped.
84
-
- If there are two schemas (one for `get` and one for `put`), resource fields are merged.
85
-
- The library looks for a creation (`POST`) and list (`GET`) path. They need to look like `/books` (plural noun).
86
-
- The deletion (`DELETE`) path needs to be inside the get / edit path.
87
-
- In order to reference the resources between themselves (embeddeds or relations), the library guesses embeddeds or references from property names.
88
-
For instance if a book schema has a `reviews` property, the library tries to find a `Review` resource.
89
-
If there is, a relation or an embedded between `Book` and `Review` resources is made for the `reviews` field.
90
-
The property name can also be like `review_id`, `reviewId`, `review_ids` or `reviewIds` for references.
91
-
- Parameters are only retrieved in the list path.
110
+
#### Swagger
92
111
93
-
## Support for other formats (JSON:API...)
112
+
```typescript
113
+
function parseSwaggerDocumentation(entrypointUrl:string):Promise<{
114
+
api:Api;
115
+
response:OpenAPIV2.Document;
116
+
status:number;
117
+
}>;
118
+
```
119
+
120
+
#### Hydra
121
+
122
+
```typescript
123
+
function parseHydraDocumentation(
124
+
entrypointUrl:string,
125
+
options?:RequestInitExtended,
126
+
):Promise<{
127
+
api:Api;
128
+
response:Response;
129
+
status:number;
130
+
}>;
131
+
```
132
+
133
+
#### GraphQL
134
+
135
+
```typescript
136
+
function parseGraphQl(
137
+
entrypointUrl:string,
138
+
options?:RequestInit,
139
+
):Promise<{
140
+
api:Api;
141
+
response:Response;
142
+
}>;
143
+
```
144
+
145
+
### Api
146
+
147
+
Represents the root of the parsed API, containing the entrypoint URL, an optional title, and a list of resources.
148
+
149
+
```typescript
150
+
interfaceApi {
151
+
entrypoint:string;
152
+
title?:string;
153
+
resources?:Resource[];
154
+
}
155
+
```
156
+
157
+
### Resource
158
+
159
+
Describes an API resource (such as an entity or collection), including its fields, operations, and metadata.
160
+
161
+
```typescript
162
+
interfaceResource {
163
+
name:string|null;
164
+
url:string|null;
165
+
id?:string|null;
166
+
title?:string|null;
167
+
description?:string|null;
168
+
deprecated?:boolean|null;
169
+
fields?:Field[] |null;
170
+
readableFields?:Field[] |null;
171
+
writableFields?:Field[] |null;
172
+
parameters?:Parameter[] |null;
173
+
getParameters?: () =>Promise<Parameter[]> |null;
174
+
operations?:Operation[] |null;
175
+
}
176
+
```
177
+
178
+
### Field
179
+
180
+
Represents a property of a resource, including its type, constraints, 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}`). |
271
+
|**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**. |
272
+
|**Collection paths**| A create (`POST`) or list (`GET`) endpoint **must** be plural:<br/>`/books`. |
273
+
|**Deletion path**|`DELETE` must live under the single-item GET path (`/books/{id}`). |
274
+
|**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_. |
275
+
|**Parameter extraction**| Parameters are read **only** from the list path (`/books`). |
276
+
277
+
## 🧩 Support for other formats (JSON:API, AsyncAPI...)
94
278
95
279
API Doc Parser is designed to parse any API documentation format and convert it in the same intermediate representation.
96
280
If you develop a parser for another format, please [open a Pull Request](https://github.com/api-platform/api-doc-parser/pulls)
97
281
to include it in the library.
98
282
99
-
## Run tests
283
+
## 🤝 Contributing
284
+
285
+
Contributions are welcome! To contribute:
286
+
287
+
1.**Read our [Code of Conduct](https://github.com/api-platform/api-doc-parser?tab=coc-ov-file#contributor-code-of-conduct).**
288
+
289
+
2.**Fork the repository and create a feature branch.**
290
+
291
+
3.**Install dependencies**
100
292
101
-
pnpm test
102
-
pnpm lint
293
+
```bash
294
+
pnpm install
295
+
```
103
296
104
-
## Credits
297
+
4.**Adhere to the code style**
298
+
299
+
```bash
300
+
pnpm lint:fix
301
+
```
302
+
303
+
```bash
304
+
pnpm format
305
+
```
306
+
307
+
5.**Run tests**
308
+
309
+
```bash
310
+
pnpm test
311
+
```
312
+
313
+
6.**Ensure type correctness**
314
+
315
+
```bash
316
+
pnpm typecheck
317
+
```
318
+
319
+
7.**Submit a pull request with a clear description of your changes.**
0 commit comments