@celljs/openapi 4.6.1 → 4.8.0
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.zh-cn.md +86 -0
- package/package.json +5 -5
package/README.zh-cn.md
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Cell - OpenAPI 组件
|
|
2
|
+
|
|
3
|
+
将 `@celljs/openapi` 添加到依赖中,以文档化你的 `@celljs/mvc` 控制器的 API:应用程序在 `/openapi.json` 提供 [OpenAPI 3.0](https://spec.openapis.org/oas/v3.0.3) 文档,在 `/api-docs` 提供 [Swagger UI](https://swagger.io/tools/swagger-ui/)。文档是从路由本身构建的(路径、`@Param` / `@Query` / `@Header` / `@Cookie` / `@Body`、TypeScript 参数和返回类型),因此始终与代码保持同步;`@Api*` 装饰器添加类型无法表达的内容。示例:[examples/openapi-app](https://github.com/cellbang/cell/tree/main/examples/openapi-app)。
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
import { Body, Controller, Get, Param, Post, Query } from '@celljs/mvc/lib/node';
|
|
7
|
+
import { ApiOperation, ApiProperty, ApiPropertyOptional, ApiResponse, ApiTags } from '@celljs/openapi';
|
|
8
|
+
import { IsInt, IsOptional, IsString, Min } from 'class-validator';
|
|
9
|
+
|
|
10
|
+
export class CreatePet {
|
|
11
|
+
@IsString() // class-validator 装饰器成为了 schema:类型、必需、枚举、长度、范围...
|
|
12
|
+
@ApiProperty({ example: 'Tom' }) // ...而 @ApiProperty 添加描述、示例或数组的类型
|
|
13
|
+
name: string;
|
|
14
|
+
|
|
15
|
+
@IsInt() @Min(0) @IsOptional()
|
|
16
|
+
age?: number;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export class Pet extends CreatePet {
|
|
20
|
+
@ApiProperty()
|
|
21
|
+
id: number;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
@Controller('pets')
|
|
25
|
+
@ApiTags('Pets')
|
|
26
|
+
export class PetController {
|
|
27
|
+
@Get()
|
|
28
|
+
@ApiResponse({ type: [Pet] }) // 异步方法和数组需要类型:TypeScript 只会发出 Promise / Array
|
|
29
|
+
list(@Query() query: PetQuery): Promise<Pet[]> { ... }
|
|
30
|
+
|
|
31
|
+
@Get(':id')
|
|
32
|
+
@ApiOperation({ summary: 'Find a pet' })
|
|
33
|
+
@ApiResponse({ status: 404, description: 'No such pet' })
|
|
34
|
+
get(@Param('id') id: number): Pet { ... } // 返回类型是 200 响应
|
|
35
|
+
|
|
36
|
+
@Post()
|
|
37
|
+
create(@Body() pet: CreatePet): Pet { ... } // body 的类是请求 schema
|
|
38
|
+
}
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
文档中包含的内容:
|
|
42
|
+
|
|
43
|
+
- **路径**:控制器的每个路由,`:id` 表示为 `{id}`;可选部分(`/users(/:id)`)生成一个有它的路径和一个没有它的路径。带有 RegExp 路径的路由被排除。
|
|
44
|
+
- **参数**:`@Param('id')`、`@Query('q')`、`@Header('x-name')`、`@Cookie('name')` 和参数的类型;`@Query() query: PetQuery` 为类的每个属性给出一个查询参数。方法中缺少的路径参数作为字符串添加。
|
|
45
|
+
- **Body**:`@Body() pet: CreatePet` 作为 `application/json` body;命名的 `@Body('name')` 参数作为对象的属性。
|
|
46
|
+
- **响应**:`@ApiResponse` 的那些(在类上对所有方法,或在方法上);如果没有 2xx 的响应,则 `200` 带有返回类型。内容类型遵循视图:默认为 JSON,`@Text()` 为 `text/plain`,`@Html()` 为 `text/html`。
|
|
47
|
+
- **Schema**:每个类成为 `components.schemas` 的一个条目,由 `$ref` 引用。其属性是那些带有 class-validator 装饰器的属性(从 class-validator 的元数据中读取,当它被安装时,例如使用 [@celljs/validation](../validation/README.md);它不是此包的依赖)或带有 `@ApiProperty` 的属性。属性是必需的,除非它有 `@IsOptional()` 或 `@ApiPropertyOptional()`。
|
|
48
|
+
- **标签**:`@ApiTags`,否则是控制器名称(去掉 `Controller`)。
|
|
49
|
+
|
|
50
|
+
| 装饰器 | 在 | 目的 |
|
|
51
|
+
| --- | --- | --- |
|
|
52
|
+
| `@ApiTags(...tags)` | 类、方法 | 对操作进行分组 |
|
|
53
|
+
| `@ApiOperation({ summary, description, operationId, deprecated })` | 方法 | 描述操作;`operationId` 默认为 `<Class>_<method>` |
|
|
54
|
+
| `@ApiResponse({ status, description, type, schema, contentType })` | 类、方法 | 一个响应;按状态重复;`type: [Pet]` 表示列表 |
|
|
55
|
+
| `@ApiProperty(options)` / `@ApiPropertyOptional(options)` | 属性 | 请求或响应类的属性;`type`、`enum`(列表或 TypeScript 枚举)、`description`、`example`、`format` 和任何其他 schema 字段 |
|
|
56
|
+
| `@ApiParam` / `@ApiQuery` / `@ApiHeader({ name, ... })` | 方法 | 描述参数,或记录方法从请求本身读取的参数 |
|
|
57
|
+
| `@ApiSecurity(name, scopes?)` / `@ApiBearerAuth()` | 类、方法 | 需要安全方案;当 `components.securitySchemes` 中没有时,`bearer` 被声明为 `@ApiBearerAuth()` |
|
|
58
|
+
| `@ApiExclude()` | 类、方法 | 将其从文档中排除 |
|
|
59
|
+
|
|
60
|
+
## 配置
|
|
61
|
+
|
|
62
|
+
```yaml
|
|
63
|
+
openapi:
|
|
64
|
+
enabled: true # false:既不提供文档也不提供 UI
|
|
65
|
+
url: /openapi.json # 在 server.path 下
|
|
66
|
+
ui:
|
|
67
|
+
enabled: true
|
|
68
|
+
url: /api-docs
|
|
69
|
+
cdn: https://cdn.jsdelivr.net/npm/swagger-ui-dist@5 # 页面从中加载 Swagger UI 的位置
|
|
70
|
+
document: # 合并到生成的文档中
|
|
71
|
+
openapi: 3.0.3
|
|
72
|
+
info:
|
|
73
|
+
title: Pet Store
|
|
74
|
+
version: 1.0.0
|
|
75
|
+
servers:
|
|
76
|
+
- url: https://api.example.com
|
|
77
|
+
components:
|
|
78
|
+
securitySchemes:
|
|
79
|
+
apiKey: { type: apiKey, in: header, name: X-API-Key }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
文档和页面响应任何控制器未应答的 GET 请求,因此应用程序的具有相同路径的路由赢得,其他请求无需付出任何代价。除非 [@celljs/security](../security/README.md) 保护它们,否则是公开的;要在生产中隐藏它们,在生产配置中设置 `enabled: false`(`cell.production.yml`)。
|
|
83
|
+
|
|
84
|
+
要写文档到文件而不启动服务器(用于 API 客户端、代码生成器或审核),从 `@celljs/cli` 的 `createTestApp()` 中获取它,如示例的 `scripts/export-openapi.ts` 所做。
|
|
85
|
+
|
|
86
|
+
`OpenApiDocumentProvider`(`@celljs/openapi/lib/node`)在代码中提供文档;重新绑定它以改变构建方式。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/openapi",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.8.0",
|
|
4
4
|
"description": "Generates the OpenAPI document of Cell controllers and serves it with Swagger UI",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cell-component",
|
|
@@ -35,10 +35,10 @@
|
|
|
35
35
|
"watch": "tsc -b -w --preserveWatchOutput"
|
|
36
36
|
},
|
|
37
37
|
"dependencies": {
|
|
38
|
-
"@celljs/core": "4.
|
|
39
|
-
"@celljs/http": "4.
|
|
40
|
-
"@celljs/mvc": "4.
|
|
41
|
-
"@celljs/web": "4.
|
|
38
|
+
"@celljs/core": "4.8.0",
|
|
39
|
+
"@celljs/http": "4.8.0",
|
|
40
|
+
"@celljs/mvc": "4.8.0",
|
|
41
|
+
"@celljs/web": "4.8.0"
|
|
42
42
|
},
|
|
43
43
|
"devDependencies": {
|
|
44
44
|
"class-validator": "^0.14.4"
|