fix: fix Swagger docs by improving comments

This commit is contained in:
xiao-kong-long
2023-12-23 11:57:18 +08:00
parent 9bef9691fb
commit 21f394847e
9 changed files with 611 additions and 549 deletions

View File

@ -102,7 +102,7 @@ paths:
"200":
description: ""
schema:
$ref: '#/definitions/object'
$ref: '#/definitions/object.Enforcer'
/api/add-group:
post:
tags:
@ -283,24 +283,6 @@ paths:
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/add-record:
post:
tags:
- Record API
description: add a record
operationId: ApiController.AddRecord
parameters:
- in: body
name: body
description: The details of the record
required: true
schema:
$ref: '#/definitions/object.Record'
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/add-resource:
post:
tags:
@ -436,7 +418,12 @@ paths:
post:
tags:
- User API
operationId: ApiController.AddUserkeys
operationId: ApiController.AddUserKeys
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/add-webhook:
post:
tags:
@ -455,11 +442,27 @@ paths:
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/api/Callback:
post:
tags:
- Callback API
description: Get Login Error Counts
operationId: ApiController.Callback
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/api/get-captcha:
get:
tags:
- Login API
operationId: ApiController.GetCaptcha
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/api/get-captcha-status:
get:
tags:
@ -482,11 +485,21 @@ paths:
tags:
- GetWebhookEventType API
operationId: ApiController.GetWebhookEventType
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/api/reset-email-or-phone:
post:
tags:
- Account API
operationId: ApiController.ResetEmailOrPhone
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/api/send-email:
post:
tags:
@ -515,6 +528,24 @@ paths:
description: object
schema:
$ref: '#/definitions/Response'
/api/api/send-notification:
post:
tags:
- Service API
description: This API is not for Casdoor frontend to call, it is for Casdoor SDKs.
operationId: ApiController.SendNotification
parameters:
- in: body
name: from
description: Details of the notification request
required: true
schema:
$ref: '#/definitions/controllers.NotificationForm'
responses:
"200":
description: object
schema:
$ref: '#/definitions/Response'
/api/api/send-sms:
post:
tags:
@ -548,11 +579,21 @@ paths:
tags:
- Verification API
operationId: ApiController.VerifyCode
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/api/webhook:
post:
tags:
- HandleOfficialAccountEvent API
operationId: ApiController.HandleOfficialAccountEvent
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/batch-enforce:
post:
tags:
@ -606,6 +647,11 @@ paths:
tags:
- User API
operationId: ApiController.CheckUserPassword
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/delete-adapter:
post:
tags:
@ -677,7 +723,7 @@ paths:
"200":
description: ""
schema:
$ref: '#/definitions/object'
$ref: '#/definitions/object.Enforcer'
/api/delete-group:
post:
tags:
@ -1265,7 +1311,7 @@ paths:
"200":
description: ""
schema:
$ref: '#/definitions/object'
$ref: '#/definitions/object.Enforcer'
/api/get-enforcers:
get:
tags:
@ -1285,6 +1331,19 @@ paths:
type: array
items:
$ref: '#/definitions/object.Enforcer'
/api/get-global-certs:
get:
tags:
- Cert API
description: get globle certs
operationId: ApiController.GetGlobalCerts
responses:
"200":
description: The Response object
schema:
type: array
items:
$ref: '#/definitions/object.Cert'
/api/get-global-providers:
get:
tags:
@ -1311,19 +1370,6 @@ paths:
type: array
items:
$ref: '#/definitions/object.User'
/api/get-global-certs:
get:
tags:
- Cert API
description: get globle certs
operationId: ApiController.GetGlobalCerts
responses:
"200":
description: The Response object
schema:
type: array
items:
$ref: '#/definitions/object.Cert'
/api/get-group:
get:
tags:
@ -1779,47 +1825,6 @@ paths:
type: array
items:
$ref: '#/definitions/object.Provider'
/api/get-records:
get:
tags:
- Record API
description: get all records
operationId: ApiController.GetRecords
parameters:
- in: query
name: pageSize
description: The size of each page
required: true
type: string
- in: query
name: p
description: The number of the page
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Record'
/api/get-records-filter:
post:
tags:
- Record API
description: get records by filter
operationId: ApiController.GetRecordsByFilter
parameters:
- in: body
name: filter
description: filter Record message
required: true
schema:
type: string
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Record'
/api/get-resource:
get:
tags:
@ -2387,46 +2392,6 @@ paths:
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/login/oauth/access_token:
post:
tags:
- Token API
description: get OAuth access token
operationId: ApiController.GetOAuthToken
parameters:
- in: query
name: grant_type
description: OAuth grant type
required: true
type: string
- in: query
name: client_id
description: OAuth client id
required: true
type: string
- in: query
name: client_secret
description: OAuth client secret
required: true
type: string
- in: query
name: code
description: OAuth code
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.TokenWrapper'
"400":
description: The Response object
schema:
$ref: '#/definitions/object.TokenError'
"401":
description: The Response object
schema:
$ref: '#/definitions/object.TokenError'
/api/login/oauth/introspect:
post:
description: The introspection endpoint is an OAuth 2.0 endpoint that takes a
@ -2500,29 +2465,6 @@ paths:
schema:
$ref: '#/definitions/object.TokenError'
/api/logout:
get:
tags:
- Login API
description: logout the current user
operationId: ApiController.Logout
parameters:
- in: query
name: id_token_hint
description: id_token_hint
type: string
- in: query
name: post_logout_redirect_uri
description: post_logout_redirect_uri
type: string
- in: query
name: state
description: state
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
post:
tags:
- Login API
@ -2620,6 +2562,11 @@ paths:
tags:
- Verification API
operationId: ApiController.SendVerificationCode
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/set-password:
post:
tags:
@ -2706,6 +2653,12 @@ paths:
post:
tags:
- Login API
operationId: ApiController.Unlink
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/update-adapter:
post:
tags:
@ -2797,7 +2750,7 @@ paths:
"200":
description: ""
schema:
$ref: '#/definitions/object'
$ref: '#/definitions/object.Enforcer'
/api/update-group:
post:
tags:
@ -3283,6 +3236,11 @@ paths:
tags:
- Verification API
operationId: ApiController.VerifyCaptcha
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/webauthn/signin/begin:
get:
tags:
@ -3310,7 +3268,7 @@ paths:
tags:
- Login API
description: WebAuthn Login Flow 2nd stage
operationId: ApiController.WebAuthnSigninBegin
operationId: ApiController.WebAuthnSigninFinish
parameters:
- in: body
name: body
@ -3352,13 +3310,47 @@ paths:
description: '"The Response object"'
schema:
$ref: '#/definitions/controllers.Response'
/apiapi/login/oauth/access_token:
post:
tags:
- Token API
description: get OAuth access token
operationId: ApiController.GetOAuthToken
parameters:
- in: query
name: grant_type
description: OAuth grant type
required: true
type: string
- in: query
name: client_id
description: OAuth client id
required: true
type: string
- in: query
name: client_secret
description: OAuth client secret
required: true
type: string
- in: query
name: code
description: OAuth code
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.TokenWrapper'
"400":
description: The Response object
schema:
$ref: '#/definitions/object.TokenError'
"401":
description: The Response object
schema:
$ref: '#/definitions/object.TokenError'
definitions:
1183.0xc000639290.false:
title: "false"
type: object
1217.0xc0006392c0.false:
title: "false"
type: object
LaravelResponse:
title: LaravelResponse
type: object
@ -3393,14 +3385,24 @@ definitions:
type: string
title:
type: string
controllers.NotificationForm:
title: NotificationForm
type: object
properties:
content:
type: string
controllers.Response:
title: Response
type: object
properties:
data:
$ref: '#/definitions/1183.0xc000639290.false'
additionalProperties:
description: support string, struct or []struct
type: string
data2:
$ref: '#/definitions/1217.0xc0006392c0.false'
additionalProperties:
description: support string, struct or []struct
type: string
msg:
type: string
name:
@ -3430,9 +3432,6 @@ definitions:
object:
title: object
type: object
object.&{197049 0xc000a2cd50 false}:
title: '&{197049 0xc000a2cd50 false}'
type: object
object.AccountItem:
title: AccountItem
type: object
@ -3468,10 +3467,10 @@ definitions:
format: int64
table:
type: string
tableNamePrefix:
type: string
type:
type: string
useSameDb:
type: boolean
user:
type: string
object.Application:
@ -3482,6 +3481,8 @@ definitions:
type: string
cert:
type: string
certPublicKey:
type: string
clientId:
type: string
clientSecret:
@ -3500,6 +3501,8 @@ definitions:
type: boolean
enablePassword:
type: boolean
enableSamlC14n10:
type: boolean
enableSamlCompress:
type: boolean
enableSignUp:
@ -3530,6 +3533,10 @@ definitions:
type: string
homepageUrl:
type: string
invitationCodes:
type: array
items:
type: string
logo:
type: string
name:
@ -3553,6 +3560,10 @@ definitions:
refreshExpireInHours:
type: integer
format: int64
samlAttributes:
type: array
items:
$ref: '#/definitions/object.SamlItem'
samlReplyUrl:
type: string
signinHtml:
@ -3581,15 +3592,11 @@ definitions:
title: CasbinRequest
type: array
items:
$ref: '#/definitions/object.&{197049 0xc000a2cd50 false}'
$ref: '#/definitions/object.CasbinRequest'
object.Cert:
title: Cert
type: object
properties:
authorityPublicKey:
type: string
authorityRootPublicKey:
type: string
bitSize:
type: integer
format: int64
@ -3905,6 +3912,8 @@ definitions:
type: string
defaultAvatar:
type: string
defaultPassword:
type: string
displayName:
type: string
enableSoftDeletion:
@ -3922,6 +3931,8 @@ definitions:
type: string
masterPassword:
type: string
masterVerificationCode:
type: string
mfaItems:
type: array
items:
@ -4011,6 +4022,8 @@ definitions:
type: string
state:
$ref: '#/definitions/pp.PaymentState'
successUrl:
type: string
tag:
type: string
type:
@ -4043,6 +4056,10 @@ definitions:
type: string
effect:
type: string
groups:
type: array
items:
type: string
isEnabled:
type: boolean
model:
@ -4091,12 +4108,17 @@ definitions:
type: string
owner:
type: string
pricePerMonth:
type: number
format: double
pricePerYear:
paymentProviders:
type: array
items:
type: string
period:
type: string
price:
type: number
format: double
product:
type: string
role:
type: string
object.Pricing:
@ -4105,10 +4127,6 @@ definitions:
properties:
application:
type: string
approveTime:
type: string
approver:
type: string
createdTime:
type: string
description:
@ -4125,10 +4143,6 @@ definitions:
type: array
items:
type: string
state:
type: string
submitter:
type: string
trialDuration:
type: integer
format: int64
@ -4278,8 +4292,6 @@ definitions:
title: ProviderItem
type: object
properties:
alertType:
type: string
canSignIn:
type: boolean
canSignUp:
@ -4296,36 +4308,7 @@ definitions:
$ref: '#/definitions/object.Provider'
rule:
type: string
object.Record:
title: Record
type: object
properties:
action:
type: string
clientIp:
type: string
createdTime:
type: string
extendedUser:
$ref: '#/definitions/object.User'
id:
type: integer
format: int64
isTriggered:
type: boolean
method:
type: string
name:
type: string
object:
type: string
organization:
type: string
owner:
type: string
requestUri:
type: string
user:
signupGroup:
type: string
object.Resource:
title: Resource
@ -4374,6 +4357,10 @@ definitions:
type: array
items:
type: string
groups:
type: array
items:
type: string
isEnabled:
type: boolean
name:
@ -4388,12 +4375,26 @@ definitions:
type: array
items:
type: string
object.SamlItem:
title: SamlItem
type: object
properties:
name:
type: string
nameformat:
type: string
value:
type: string
object.SignupItem:
title: SignupItem
type: object
properties:
label:
type: string
name:
type: string
placeholder:
type: string
prompted:
type: boolean
required:
@ -4406,39 +4407,45 @@ definitions:
title: Subscription
type: object
properties:
approveTime:
type: string
approver:
type: string
createdTime:
type: string
description:
type: string
displayName:
type: string
duration:
type: integer
format: int64
endDate:
endTime:
type: string
format: datetime
isEnabled:
type: boolean
name:
type: string
owner:
type: string
payment:
type: string
period:
type: string
plan:
type: string
startDate:
pricing:
type: string
startTime:
type: string
format: datetime
state:
type: string
submitter:
type: string
$ref: '#/definitions/object.SubscriptionState'
user:
type: string
object.SubscriptionState:
title: SubscriptionState
type: string
enum:
- SubStatePending = "Pending"
- SubStateError = "Error"
- SubStateSuspended = "Suspended"
- SubStateActive = "Active"
- SubStateUpcoming = "Upcoming"
- SubStateExpired = "Expired"
example: Pending
object.Syncer:
title: Syncer
type: object
@ -4472,6 +4479,8 @@ definitions:
port:
type: integer
format: int64
sslMode:
type: string
syncInterval:
type: integer
format: int64
@ -4524,6 +4533,8 @@ definitions:
properties:
accessToken:
type: string
accessTokenHash:
type: string
application:
type: string
code:
@ -4548,6 +4559,8 @@ definitions:
type: string
refreshToken:
type: string
refreshTokenHash:
type: string
scope:
type: string
tokenType:
@ -4609,6 +4622,8 @@ definitions:
type: string
azuread:
type: string
azureadb2c:
type: string
baidu:
type: string
battlenet:
@ -4659,6 +4674,8 @@ definitions:
type: boolean
eveonline:
type: string
externalId:
type: string
facebook:
type: string
firstName:
@ -4894,6 +4911,8 @@ definitions:
type: string
email:
type: string
email_verified:
type: boolean
groups:
type: array
items: