typoa 1.0.0-alpha.7 → 1.0.0-alpha.71
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -21
- package/build/controller.d.ts +2 -1
- package/build/controller.js +279 -74
- package/build/index.d.ts +90 -7
- package/build/index.js +177 -48
- package/build/logger.d.ts +5 -0
- package/build/logger.js +18 -0
- package/build/openapi.js +2 -3
- package/build/option.d.ts +33 -0
- package/build/option.js +27 -0
- package/build/resolve.d.ts +11 -3
- package/build/resolve.js +670 -112
- package/build/runtime/decorators.d.ts +12 -6
- package/build/runtime/decorators.js +53 -35
- package/build/runtime/index.d.ts +5 -0
- package/build/runtime/index.js +47 -0
- package/build/runtime/interfaces.js +3 -5
- package/build/runtime/ref.d.ts +1 -0
- package/build/runtime/ref.js +7 -0
- package/build/runtime/response.d.ts +1 -1
- package/build/runtime/response.js +21 -9
- package/build/runtime/validator.d.ts +8 -0
- package/build/runtime/validator.js +432 -115
- package/build/template/express.ts.hbs +23 -7
- package/build/types.d.ts +16 -1
- package/build/utils.d.ts +13 -1
- package/build/utils.js +124 -16
- package/package.json +60 -37
package/README.md
CHANGED
|
@@ -3,16 +3,15 @@
|
|
|
3
3
|
<h1>typoa</h1>
|
|
4
4
|
<h2> <b>Typ</b>escript <b>O</b>pen<b>A</b>PI Generator</h2>
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
This tools is inspired from [tsoa](https://github.com/lukeautry/tsoa), the purpose is to be able to generate openapi definitions and express routes definitions via Typescript typings.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
We're using [ts-morph](https://github.com/dsherret/ts-morph) under the hood.
|
|
9
9
|
|
|
10
|
-
[](https://codecov.io/gh/Eywek/typoa)
|
|
11
10
|
</div>
|
|
12
11
|
|
|
13
12
|
## Why
|
|
14
13
|
|
|
15
|
-
Tsoa is a great package and it's working fine for simple typescript typings, which I think are
|
|
14
|
+
Tsoa is a great package and it's working fine for simple typescript typings, which I think are principal use cases, it's used by many developers and maintained.
|
|
16
15
|
|
|
17
16
|
**BUT**, I've used tsoa in production projects and I've encountered many issues (I was able to [fix](https://github.com/lukeautry/tsoa/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Amerged+author%3AEywek) some of them), but when I've tried to use more complex types (inheritance, deep generics, conditionnal types...) tsoa wasn't able to provide me good openapi definitions, and without even telling me it failed to generate the right schema.
|
|
18
17
|
|
|
@@ -37,12 +36,12 @@ You only need to add the `@Route()` decorator at the top of your controller clas
|
|
|
37
36
|
of each method definition, like this:
|
|
38
37
|
|
|
39
38
|
```ts
|
|
40
|
-
import { Route, Get } from 'typoa'
|
|
39
|
+
import { Route, Get } from 'typoa/runtime'
|
|
41
40
|
|
|
42
41
|
@Route()
|
|
43
42
|
class MyController {
|
|
44
43
|
@Get()
|
|
45
|
-
public get
|
|
44
|
+
public get() {}
|
|
46
45
|
}
|
|
47
46
|
```
|
|
48
47
|
|
|
@@ -51,12 +50,12 @@ You can provide the route path in the `@Route()` decorator or in each verb decor
|
|
|
51
50
|
You also will need to extends the `Controller` class if you want to override the default HTTP status (200 if your method return content, 204 if not):
|
|
52
51
|
|
|
53
52
|
```ts
|
|
54
|
-
import { Route, Get, Controller } from 'typoa'
|
|
53
|
+
import { Route, Get, Controller } from 'typoa/runtime'
|
|
55
54
|
|
|
56
55
|
@Route('/controller-path')
|
|
57
56
|
class MyController extends Controller {
|
|
58
57
|
@Get('/method-path')
|
|
59
|
-
public get
|
|
58
|
+
public get() {
|
|
60
59
|
this.setStatus(201)
|
|
61
60
|
return 'Created'
|
|
62
61
|
}
|
|
@@ -71,14 +70,12 @@ If you return a stream, `typoa` will stream it to the client.
|
|
|
71
70
|
To use the parsed (and validated) body from typoa you only need to provide the `@Body()` decorator:
|
|
72
71
|
|
|
73
72
|
```ts
|
|
74
|
-
import { Route, Get, Controller } from 'typoa'
|
|
73
|
+
import { Route, Get, Controller } from 'typoa/runtime'
|
|
75
74
|
|
|
76
75
|
@Route('/controller-path')
|
|
77
76
|
class MyController extends Controller {
|
|
78
77
|
@Post('/method-path')
|
|
79
|
-
public post
|
|
80
|
-
@Body() body: { name: string }
|
|
81
|
-
) {
|
|
78
|
+
public post(@Body() body: { name: string }) {
|
|
82
79
|
this.setStatus(201)
|
|
83
80
|
return 'Created'
|
|
84
81
|
}
|
|
@@ -98,22 +95,29 @@ Sometimes you want to validate the body against a specific schema depending on w
|
|
|
98
95
|
To handle that, you can provide a `discriminator function` to the body decorator:
|
|
99
96
|
|
|
100
97
|
```ts
|
|
101
|
-
import {
|
|
98
|
+
import {
|
|
99
|
+
Route,
|
|
100
|
+
Get,
|
|
101
|
+
Controller,
|
|
102
|
+
BodyDiscriminatorFunction
|
|
103
|
+
} from 'typoa/runtime'
|
|
102
104
|
|
|
103
105
|
type TypeA = { name: string }
|
|
104
106
|
type TypeB = { name: number }
|
|
105
107
|
|
|
106
108
|
// The function need to return the name of the type you want to validate against
|
|
107
|
-
export const discriminatorFunction: BodyDiscriminatorFunction = async
|
|
109
|
+
export const discriminatorFunction: BodyDiscriminatorFunction = async req =>
|
|
110
|
+
'TypeA'
|
|
108
111
|
|
|
109
112
|
@Route('/controller-path')
|
|
110
113
|
class MyController extends Controller {
|
|
111
114
|
@Post('/method-path')
|
|
112
|
-
public post
|
|
115
|
+
public post(
|
|
113
116
|
@Body(
|
|
114
117
|
'application/json', // body content-type
|
|
115
118
|
discriminatorFunction // name of the function you want to use
|
|
116
|
-
)
|
|
119
|
+
)
|
|
120
|
+
body: TypeA | TypeB
|
|
117
121
|
) {
|
|
118
122
|
this.setStatus(201)
|
|
119
123
|
return 'Created'
|
|
@@ -126,23 +130,30 @@ class MyController extends Controller {
|
|
|
126
130
|
To generate the openapi definition and the router you will need to bind to express, you only need to call the `generate` method of `typoa`:
|
|
127
131
|
|
|
128
132
|
```ts
|
|
133
|
+
import { generate } from 'typoa'
|
|
134
|
+
|
|
129
135
|
await generate({
|
|
130
136
|
tsconfigFilePath: path.resolve(__dirname, './tsconfig.json'),
|
|
131
137
|
controllers: [path.resolve(__dirname, './*.ts')], // Path of your controllers
|
|
132
138
|
openapi: {
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
139
|
+
// Where do you want to generate your openapi file (or array of file paths)
|
|
140
|
+
// The file extension (.json, .yaml, or .yml) determines the output format
|
|
141
|
+
filePath: '/tmp/openapi.json',
|
|
142
|
+
service: {
|
|
143
|
+
// Used in the openapi definitions
|
|
136
144
|
name: 'my-service',
|
|
137
145
|
version: '1.0.0'
|
|
138
146
|
},
|
|
139
|
-
securitySchemes: {
|
|
147
|
+
securitySchemes: {
|
|
148
|
+
// Openapi securitySchemes definitions
|
|
140
149
|
company: {
|
|
141
150
|
type: 'apiKey',
|
|
142
151
|
name: 'x-company-id',
|
|
143
152
|
in: 'header'
|
|
144
153
|
}
|
|
145
|
-
}
|
|
154
|
+
},
|
|
155
|
+
// Optional, fail on a misspelled JSDoc tag (e.g. @minLenght) instead of a logger warning
|
|
156
|
+
strictJsDocTags: true
|
|
146
157
|
},
|
|
147
158
|
router: {
|
|
148
159
|
filePath: './router.ts', // Where do you want to generate the router file
|
|
@@ -150,3 +161,15 @@ await generate({
|
|
|
150
161
|
}
|
|
151
162
|
})
|
|
152
163
|
```
|
|
164
|
+
|
|
165
|
+
### Runtime imports
|
|
166
|
+
|
|
167
|
+
`typoa` is the generator entry point and loads `ts-morph` (the TypeScript compiler), which costs tens of MiB of memory.
|
|
168
|
+
Code that runs in your service (controllers, decorators, `Controller`, `setRuntimeOptions`...) should import from `typoa/runtime` instead, which never loads it:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
import { Route, Get, Controller, setRuntimeOptions } from 'typoa/runtime'
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Keep `import { generate } from 'typoa'` in your generation script only.
|
|
175
|
+
The generated router imports from `typoa/runtime` by default (override with `router.runtimeImport`).
|
package/build/controller.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { OpenAPIV3 } from 'openapi-types';
|
|
2
2
|
import { ClassDeclaration } from 'ts-morph';
|
|
3
3
|
import { CodeGenControllers } from './types';
|
|
4
|
-
|
|
4
|
+
import { OpenAPIConfiguration } from './';
|
|
5
|
+
export declare function addController(controller: ClassDeclaration, spec: OpenAPIV3.Document, codegenControllers: CodeGenControllers, config: OpenAPIConfiguration['router']): void;
|