Skip to content

Commit e5b4a61

Browse files
kerwanpkerwanp
committed
openapi-decorators documentation
1 parent 016d2f6 commit e5b4a61

File tree

5 files changed

+229
-5
lines changed

5 files changed

+229
-5
lines changed

‎docs/.vitepress/en.ts

+7-4
Original file line numberDiff line numberDiff line change
@@ -82,10 +82,13 @@ export const en = defineConfig({
8282
text: "openapi-adonis",
8383
items: [
8484
{ text: "Getting Started", link: "/openapi-adonis/" },
85-
{ text: "useQuery", link: "/openapi-react-query/use-query" },
86-
{ text: "useMutation", link: "/openapi-react-query/use-mutation" },
87-
{ text: "useSuspenseQuery", link: "/openapi-react-query/use-suspense-query" },
88-
{ text: "About", link: "/openapi-react-query/about" },
85+
],
86+
},
87+
{
88+
text: "openapi-decorators",
89+
items: [
90+
{ text: "Getting Started", link: "/openapi-decorators/" },
91+
{ text: "Decorators", link: "/openapi-decorators/decorators" },
8992
],
9093
},
9194
],

‎docs/data/contributors.json

+1-1
Large diffs are not rendered by default.

‎docs/openapi-adonis/decorators.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: openapi-adonis
3+
---
4+
5+
## `@apiProperty`
6+
7+

‎docs/openapi-decorators/decorators.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Decorators
3+
---
4+
5+
# Decorators
6+
7+
Decorators are used to enrich your OpenAPI specifications. They can be applied on a Controller, a Method or a Model. They are all prefixed with `api`.
8+
9+
> For more information about the decorators, you can directly refer to the [source code](https://github.com/openapi-ts/openapi-typescript/packages/openapi-decorators/src/decorators).
10+
11+
| Decorator | Usage | Description |
12+
|-|-|-|
13+
| `@apiProperty` | Model | Configures a schema property. |
14+
| `@apiTags` | Controller / Method | Adds tags to the operation. When applied on a controller, the tags are applied to all of its operations. |
15+
| `@apiOperation` | Method | Configures an operation. |
16+
| `@apiQuery` | Method | Adds a query parameter to the operation. |
17+
| `@apiParam` | Method | Adds a path parameter to the operation. |
18+
| `@apiResponse` | Method | Adds a response to the operation. |
19+
| `@apiBody` | Method | Sets the requestBody of the operation. |
20+

‎docs/openapi-decorators/index.md

+194
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
title: 'Getting started'
3+
---
4+
5+
# Introduction
6+
7+
`openapi-decorators` is a framework agnostic library to automatically generate OpenAPI schemas and documentation by using Typescript decorators and metadata.
8+
9+
::: code-group
10+
11+
```ts [users_controller.ts]
12+
import { apiOperation, apiResponse } from "openapi-adonis/decorators";
13+
import User from "./user";
14+
15+
class UsersController {
16+
@apiOperation({
17+
method: "get",
18+
pattern: "/users",
19+
summary: "List users"
20+
})
21+
@apiResponse({ type: [User] })
22+
async list() {
23+
...
24+
}
25+
}
26+
```
27+
28+
```ts [user.ts]
29+
import { apiProperty } from "openapi-adonis/decorators";
30+
31+
class User {
32+
@apiProperty()
33+
declare id: number;
34+
35+
@apiProperty()
36+
declare name: string;
37+
38+
@apiProperty({ required: false })
39+
declare mobile?: string;
40+
}
41+
```
42+
43+
```ts [index.ts]
44+
import "reflect-metadata";
45+
import { DocumentBuilder } from "openapi-decorators/builders";
46+
import { loadController } from "openapi-decorators/loaders";
47+
import UsersController from "./users_controller";
48+
49+
const builder = new DocumentBuilder()
50+
.setTitle("My API")
51+
.setVersion("1.0.0");
52+
53+
await loadController(builder, UsersController);
54+
55+
console.log(document.build()); // <- Your generated OpenAPI specifications
56+
```
57+
58+
:::
59+
60+
## Getting started
61+
62+
### Setup
63+
64+
Install `openapi-decorators` and `reflect-metadata` using your favorite package manager.
65+
66+
```bash
67+
npm install openapi-decorators reflect-metadata
68+
```
69+
70+
Import `reflect-metadata` in your main file.
71+
72+
::: code-group
73+
74+
```ts [index.ts]
75+
import "reflect-metadata";
76+
77+
// Rest of your app
78+
```
79+
80+
:::
81+
82+
Enable `experimentalDecorators` and `experimentalDecorators`.
83+
84+
85+
::: code-group
86+
87+
```json [tsconfig.json]
88+
{
89+
"compilerOptions": {
90+
"emitDecoratorMetadata": true,
91+
"experimentalDecorators": true,
92+
}
93+
}
94+
```
95+
96+
:::
97+
98+
### Create your OpenAPI document
99+
100+
To get started, create a new DocumentBuilder. It will hold all the informations required to generate your OpenAPI specifications.
101+
By using the method `build()` you can already have an (almost) empty documentation.
102+
103+
::: code-group
104+
105+
```ts [index.ts]
106+
import "reflect-metadata";
107+
import { DocumentBuilder } from "openapi-decorators/builders";
108+
109+
const builder = new DocumentBuilder()
110+
.setTitle("My API")
111+
.setVersion("1.0.0");
112+
113+
console.log(document.build()); // <- Your generated OpenAPI specifications
114+
```
115+
116+
:::
117+
118+
### Create your first model
119+
120+
Using the `apiProperty` decorator on class properties will allow your operations to use the class as a schema.
121+
122+
> Unlike other libraries like `@nestjs/swagger`, every element of your OpenAPI schema is lazy-loaded. Your models will only be part of your documentation if it is used.
123+
124+
::: code-group
125+
126+
```ts [user.ts]
127+
import { apiProperty } from "openapi-decorators/decorators";
128+
129+
class User {
130+
@apiProperty()
131+
declare id: string;
132+
133+
@apiProperty({ example: "John Doe" })
134+
declare name: string;
135+
136+
@apiProperty()
137+
declare email: string;
138+
139+
@apiProperty({ required: false })
140+
declare mobile?: string;
141+
}
142+
```
143+
144+
:::
145+
146+
### Create your first controller
147+
148+
Next we need to define our first operation. We can do this by using a controller.
149+
150+
In the following example we create an operation `GET /users` that returns a list of `User`.
151+
152+
::: code-group
153+
154+
```ts [users_controller.ts]
155+
import { apiOperation, apiResponse } from "openapi-decorators/decorators";
156+
import User from "./user";
157+
158+
class UsersController {
159+
@apiOperation({
160+
method: "get",
161+
pattern: "/users",
162+
summary: "List users"
163+
})
164+
@apiResponse({ type: [User] })
165+
async list() {
166+
...
167+
}
168+
}
169+
```
170+
171+
:::
172+
173+
### Load the controller into your DocumentBuilder
174+
175+
You now simply have to load the controller into your DocumentBuilder and tada 🎉.
176+
177+
::: code-group
178+
179+
```ts [index.ts]
180+
import "reflect-metadata";
181+
import { DocumentBuilder } from "openapi-decorators/builders";
182+
import { loadController } from "openapi-decorators/loaders";
183+
import UsersController from "./users_controller";
184+
185+
const builder = new DocumentBuilder()
186+
.setTitle("My API")
187+
.setVersion("1.0.0");
188+
189+
await loadController(builder, UsersController);
190+
191+
console.log(document.build()); // <- Your generated OpenAPI specifications
192+
```
193+
194+
:::

0 commit comments

Comments
 (0)