Skip to content

Commit 472baaf

Browse files
czy88840616czy88840616
committed
docs: update swagger security decorator default value
1 parent 4d22be7 commit 472baaf

File tree

4 files changed

+169
-17
lines changed

4 files changed

+169
-17
lines changed

‎site/docs/extensions/swagger.md‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -774,7 +774,16 @@ export default {
774774
在控制器层面生效。
775775

776776
```typescript
777-
@ApiBasicAuth()
777+
@ApiBasicAuth() // 默认使用 'basic' 作为名称
778+
@Controller('/hello')
779+
export class HelloController {}
780+
```
781+
782+
**注意**：`@ApiBasicAuth()` 装饰器有默认值 `'basic'`。如果配置文件中的 `name` 字段不是 `'basic'`，需要在装饰器中显式指定相同的名称：
783+
784+
```typescript
785+
// 配置文件中 name 为 'BasicAuth' 时
786+
@ApiBasicAuth('BasicAuth')
778787
@Controller('/hello')
779788
export class HelloController {}
780789
```
@@ -812,7 +821,16 @@ export default {
812821
在控制器层面生效。
813822

814823
```typescript
815-
@ApiBearerAuth()
824+
@ApiBearerAuth() // 默认使用 'bearer' 作为名称
825+
@Controller('/hello')
826+
export class HelloController {}
827+
```
828+
829+
**注意**：`@ApiBearerAuth()` 装饰器有默认值 `'bearer'`。如果配置文件中的 `name` 字段不是 `'bearer'`，需要在装饰器中显式指定相同的名称：
830+
831+
```typescript
832+
// 配置文件中 name 为 'BearerAuth' 时
833+
@ApiBearerAuth('BearerAuth')
816834
@Controller('/hello')
817835
export class HelloController {}
818836
```
@@ -829,7 +847,7 @@ export default {
829847
// ...
830848
swagger: {
831849
auth: {
832-
name: 'testOAuth2'
850+
name: 'testOAuth2',
833851
authType: 'oauth2',
834852
flows: {
835853
implicit: {
@@ -886,7 +904,16 @@ flows 是其中最复杂的字段配置，包括不同的参数，目前主要
886904
在控制器层面生效。
887905

888906
```typescript
889-
@ApiOAuth2()
907+
@ApiOAuth2(['read:pets']) // 必须指定权限范围，默认使用 'oauth2' 作为名称
908+
@Controller('/hello')
909+
export class HelloController {}
910+
```
911+
912+
**注意**：`@ApiOAuth2()` 装饰器有默认值 `'oauth2'`。如果配置文件中的 `name` 字段不是 `'oauth2'`，需要在装饰器中显式指定相同的名称：
913+
914+
```typescript
915+
// 配置文件中 name 为 'testOAuth2' 时
916+
@ApiOAuth2(['read:pets'], 'testOAuth2')
890917
@Controller('/hello')
891918
export class HelloController {}
892919
```
@@ -926,6 +953,15 @@ export default {
926953
在控制器层面生效。
927954

928955
```typescript
956+
@ApiCookieAuth() // 默认使用 'cookie' 作为名称
957+
@Controller('/hello')
958+
export class HelloController {}
959+
```
960+
961+
**注意**：`@ApiCookieAuth()` 装饰器有默认值 `'cookie'`。如果配置文件中的 `name` 字段不是 `'cookie'`，需要在装饰器中显式指定相同的名称：
962+
963+
```typescript
964+
// 配置文件中 name 为 'testforcookie' 时
929965
@ApiCookieAuth('testforcookie')
930966
@Controller('/hello')
931967
export class HelloController {}
@@ -969,11 +1005,13 @@ export default {
9691005
在控制器层面生效。
9701006

9711007
```typescript
972-
@ApiSecurity('api_key')
1008+
@ApiSecurity('api_key') // 必须指定名称，无默认值
9731009
@Controller('/hello')
9741010
export class HelloController {}
9751011
```
9761012

1013+
**注意**：`@ApiSecurity()` 装饰器必须指定名称参数，与配置文件中的 `name` 字段保持一致。
1014+
9771015

9781016

9791017
### custom 验证

‎site/i18n/en/docusaurus-plugin-content-docs/current/extensions/swagger.md‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -865,7 +865,16 @@ Field description
865865
Take effect at the controller level.
866866

867867
```typescript
868-
@ApiBasicAuth()
868+
@ApiBasicAuth() // default uses 'basic' as the name
869+
@Controller('/hello')
870+
export class HelloController {}
871+
```
872+
873+
Note: The `@ApiBasicAuth()` decorator has a default name `'basic'`. If the `name` field in the configuration file is not `'basic'`, you need to explicitly specify the same name in the decorator:
874+
875+
```typescript
876+
// When the name in the config file is 'BasicAuth'
877+
@ApiBasicAuth('BasicAuth')
869878
@Controller('/hello')
870879
export class HelloController {}
871880
```
@@ -902,7 +911,16 @@ Field description
902911
Take effect at the controller level.
903912

904913
```typescript
905-
@ApiBearerAuth()
914+
@ApiBearerAuth() // default uses 'bearer' as the name
915+
@Controller('/hello')
916+
export class HelloController {}
917+
```
918+
919+
Note: The `@ApiBearerAuth()` decorator has a default name `'bearer'`. If the `name` field in the configuration file is not `'bearer'`, you need to explicitly specify the same name in the decorator:
920+
921+
```typescript
922+
// When the name in the config file is 'BearerAuth'
923+
@ApiBearerAuth('BearerAuth')
906924
@Controller('/hello')
907925
export class HelloController {}
908926
```
@@ -973,7 +991,16 @@ The available parameters for the above four Flow types are as follows:
973991
Take effect at the controller level.
974992

975993
```typescript
976-
@ApiOAuth2()
994+
@ApiOAuth2(['read:pets']) // scopes must be specified, default uses 'oauth2' as the name
995+
@Controller('/hello')
996+
export class HelloController {}
997+
```
998+
999+
Note: The `@ApiOAuth2()` decorator has a default name `'oauth2'`. If the `name` field in the configuration file is not `'oauth2'`, you need to explicitly specify the same name in the decorator:
1000+
1001+
```typescript
1002+
// When the name in the config file is 'testOAuth2'
1003+
@ApiOAuth2(['read:pets'], 'testOAuth2')
9771004
@Controller('/hello')
9781005
export class HelloController {}
9791006
```
@@ -1010,6 +1037,15 @@ Field description
10101037
Take effect at the controller level.
10111038

10121039
```typescript
1040+
@ApiCookieAuth() // default uses 'cookie' as the name
1041+
@Controller('/hello')
1042+
export class HelloController {}
1043+
```
1044+
1045+
Note: The `@ApiCookieAuth()` decorator has a default name `'cookie'`. If the `name` field in the configuration file is not `'cookie'`, you need to explicitly specify the same name in the decorator:
1046+
1047+
```typescript
1048+
// When the name in the config file is 'testforcookie'
10131049
@ApiCookieAuth('testforcookie')
10141050
@Controller('/hello')
10151051
export class HelloController {}
@@ -1048,11 +1084,13 @@ Field description
10481084
Take effect at the controller level.
10491085

10501086
```typescript
1051-
@ApiSecurity('api_key')
1087+
@ApiSecurity('api_key') // name must be specified, no default value
10521088
@Controller('/hello')
10531089
export class HelloController {}
10541090
```
10551091

1092+
Note: The `@ApiSecurity()` decorator must specify the name parameter, which should be consistent with the `name` field in the configuration file.
1093+
10561094
### custom authentication
10571095

10581096
Custom authentication method, you need to design the parameter configuration yourself.

‎site/i18n/en/docusaurus-plugin-content-docs/version-3.0.0/extensions/swagger.md‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -865,7 +865,16 @@ Field description
865865
Take effect at the controller level.
866866

867867
```typescript
868-
@ApiBasicAuth()
868+
@ApiBasicAuth() // default uses 'basic' as the name
869+
@Controller('/hello')
870+
export class HelloController {}
871+
```
872+
873+
Note: The `@ApiBasicAuth()` decorator has a default name `'basic'`. If the `name` field in the configuration file is not `'basic'`, you need to explicitly specify the same name in the decorator:
874+
875+
```typescript
876+
// When the name in the config file is 'BasicAuth'
877+
@ApiBasicAuth('BasicAuth')
869878
@Controller('/hello')
870879
export class HelloController {}
871880
```
@@ -902,7 +911,16 @@ Field description
902911
Take effect at the controller level.
903912

904913
```typescript
905-
@ApiBearerAuth()
914+
@ApiBearerAuth() // default uses 'bearer' as the name
915+
@Controller('/hello')
916+
export class HelloController {}
917+
```
918+
919+
Note: The `@ApiBearerAuth()` decorator has a default name `'bearer'`. If the `name` field in the configuration file is not `'bearer'`, you need to explicitly specify the same name in the decorator:
920+
921+
```typescript
922+
// When the name in the config file is 'BearerAuth'
923+
@ApiBearerAuth('BearerAuth')
906924
@Controller('/hello')
907925
export class HelloController {}
908926
```
@@ -973,7 +991,16 @@ The available parameters for the above four Flow types are as follows:
973991
Take effect at the controller level.
974992

975993
```typescript
976-
@ApiOAuth2()
994+
@ApiOAuth2(['read:pets']) // scopes must be specified, default uses 'oauth2' as the name
995+
@Controller('/hello')
996+
export class HelloController {}
997+
```
998+
999+
Note: The `@ApiOAuth2()` decorator has a default name `'oauth2'`. If the `name` field in the configuration file is not `'oauth2'`, you need to explicitly specify the same name in the decorator:
1000+
1001+
```typescript
1002+
// When the name in the config file is 'testOAuth2'
1003+
@ApiOAuth2(['read:pets'], 'testOAuth2')
9771004
@Controller('/hello')
9781005
export class HelloController {}
9791006
```
@@ -1010,6 +1037,15 @@ Field description
10101037
Take effect at the controller level.
10111038

10121039
```typescript
1040+
@ApiCookieAuth() // default uses 'cookie' as the name
1041+
@Controller('/hello')
1042+
export class HelloController {}
1043+
```
1044+
1045+
Note: The `@ApiCookieAuth()` decorator has a default name `'cookie'`. If the `name` field in the configuration file is not `'cookie'`, you need to explicitly specify the same name in the decorator:
1046+
1047+
```typescript
1048+
// When the name in the config file is 'testforcookie'
10131049
@ApiCookieAuth('testforcookie')
10141050
@Controller('/hello')
10151051
export class HelloController {}
@@ -1048,11 +1084,13 @@ Field description
10481084
Take effect at the controller level.
10491085

10501086
```typescript
1051-
@ApiSecurity('api_key')
1087+
@ApiSecurity('api_key') // name must be specified, no default value
10521088
@Controller('/hello')
10531089
export class HelloController {}
10541090
```
10551091

1092+
Note: The `@ApiSecurity()` decorator must specify the name parameter, which should be consistent with the `name` field in the configuration file.
1093+
10561094
### custom authentication
10571095

10581096
Custom authentication method, you need to design the parameter configuration yourself.

‎site/versioned_docs/version-3.0.0/extensions/swagger.md‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -774,7 +774,16 @@ export default {
774774
在控制器层面生效。
775775

776776
```typescript
777-
@ApiBasicAuth()
777+
@ApiBasicAuth() // 默认使用 'basic' 作为名称
778+
@Controller('/hello')
779+
export class HelloController {}
780+
```
781+
782+
**注意**：`@ApiBasicAuth()` 装饰器有默认值 `'basic'`。如果配置文件中的 `name` 字段不是 `'basic'`，需要在装饰器中显式指定相同的名称：
783+
784+
```typescript
785+
// 配置文件中 name 为 'BasicAuth' 时
786+
@ApiBasicAuth('BasicAuth')
778787
@Controller('/hello')
779788
export class HelloController {}
780789
```
@@ -812,7 +821,16 @@ export default {
812821
在控制器层面生效。
813822

814823
```typescript
815-
@ApiBearerAuth()
824+
@ApiBearerAuth() // 默认使用 'bearer' 作为名称
825+
@Controller('/hello')
826+
export class HelloController {}
827+
```
828+
829+
**注意**：`@ApiBearerAuth()` 装饰器有默认值 `'bearer'`。如果配置文件中的 `name` 字段不是 `'bearer'`，需要在装饰器中显式指定相同的名称：
830+
831+
```typescript
832+
// 配置文件中 name 为 'BearerAuth' 时
833+
@ApiBearerAuth('BearerAuth')
816834
@Controller('/hello')
817835
export class HelloController {}
818836
```
@@ -886,7 +904,16 @@ flows 是其中最复杂的字段配置，包括不同的参数，目前主要
886904
在控制器层面生效。
887905

888906
```typescript
889-
@ApiOAuth2()
907+
@ApiOAuth2(['read:pets']) // 必须指定权限范围，默认使用 'oauth2' 作为名称
908+
@Controller('/hello')
909+
export class HelloController {}
910+
```
911+
912+
**注意**：`@ApiOAuth2()` 装饰器有默认值 `'oauth2'`。如果配置文件中的 `name` 字段不是 `'oauth2'`，需要在装饰器中显式指定相同的名称：
913+
914+
```typescript
915+
// 配置文件中 name 为 'testOAuth2' 时
916+
@ApiOAuth2(['read:pets'], 'testOAuth2')
890917
@Controller('/hello')
891918
export class HelloController {}
892919
```
@@ -926,6 +953,15 @@ export default {
926953
在控制器层面生效。
927954

928955
```typescript
956+
@ApiCookieAuth() // 默认使用 'cookie' 作为名称
957+
@Controller('/hello')
958+
export class HelloController {}
959+
```
960+
961+
**注意**：`@ApiCookieAuth()` 装饰器有默认值 `'cookie'`。如果配置文件中的 `name` 字段不是 `'cookie'`，需要在装饰器中显式指定相同的名称：
962+
963+
```typescript
964+
// 配置文件中 name 为 'testforcookie' 时
929965
@ApiCookieAuth('testforcookie')
930966
@Controller('/hello')
931967
export class HelloController {}
@@ -969,11 +1005,13 @@ export default {
9691005
在控制器层面生效。
9701006

9711007
```typescript
972-
@ApiSecurity('api_key')
1008+
@ApiSecurity('api_key') // 必须指定名称，无默认值
9731009
@Controller('/hello')
9741010
export class HelloController {}
9751011
```
9761012

1013+
**注意**：`@ApiSecurity()` 装饰器必须指定名称参数，与配置文件中的 `name` 字段保持一致。
1014+
9771015

9781016

9791017
### custom 验证

0 commit comments

Comments
 (0)