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

@ -238,7 +238,7 @@ func (c *ApiController) Signup() {
// @Param post_logout_redirect_uri query string false "post_logout_redirect_uri"
// @Param state query string false "state"
// @Success 200 {object} controllers.Response The Response object
// @router /logout [get,post]
// @router /logout [post]
func (c *ApiController) Logout() {
// https://openid.net/specs/openid-connect-rpinitiated-1_0-final.html
accessToken := c.Input().Get("id_token_hint")
@ -454,6 +454,7 @@ func (c *ApiController) GetUserinfo2() {
// @Tag Login API
// @Title GetCaptcha
// @router /api/get-captcha [get]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) GetCaptcha() {
applicationId := c.Input().Get("applicationId")
isCurrentProvider := c.Input().Get("isCurrentProvider")

View File

@ -887,6 +887,7 @@ func (c *ApiController) HandleSamlLogin() {
// @Tag HandleOfficialAccountEvent API
// @Title HandleOfficialAccountEvent
// @router /api/webhook [POST]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) HandleOfficialAccountEvent() {
respBytes, err := ioutil.ReadAll(c.Ctx.Request.Body)
if err != nil {
@ -917,6 +918,7 @@ func (c *ApiController) HandleOfficialAccountEvent() {
// @Tag GetWebhookEventType API
// @Title GetWebhookEventType
// @router /api/get-webhook-event [GET]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) GetWebhookEventType() {
lock.Lock()
defer lock.Unlock()
@ -964,6 +966,7 @@ func (c *ApiController) GetCaptchaStatus() {
// @Tag Callback API
// @Description Get Login Error Counts
// @router /api/Callback [post]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) Callback() {
code := c.GetString("code")
state := c.GetString("state")

View File

@ -71,7 +71,7 @@ func (c *ApiController) GetEnforcers() {
// @Tag Enforcer API
// @Description get enforcer
// @Param id query string true "The id ( owner/name ) of enforcer"
// @Success 200 {object} object
// @Success 200 {object} object.Enforcer
// @router /get-enforcer [get]
func (c *ApiController) GetEnforcer() {
id := c.Input().Get("id")
@ -99,7 +99,7 @@ func (c *ApiController) GetEnforcer() {
// @Description update enforcer
// @Param id query string true "The id ( owner/name ) of enforcer"
// @Param enforcer body object true "The enforcer object"
// @Success 200 {object} object
// @Success 200 {object} object.Enforcer
// @router /update-enforcer [post]
func (c *ApiController) UpdateEnforcer() {
id := c.Input().Get("id")
@ -120,7 +120,7 @@ func (c *ApiController) UpdateEnforcer() {
// @Tag Enforcer API
// @Description add enforcer
// @Param enforcer body object true "The enforcer object"
// @Success 200 {object} object
// @Success 200 {object} object.Enforcer
// @router /add-enforcer [post]
func (c *ApiController) AddEnforcer() {
enforcer := object.Enforcer{}
@ -139,7 +139,7 @@ func (c *ApiController) AddEnforcer() {
// @Tag Enforcer API
// @Description delete enforcer
// @Param body body object.Enforce true "The enforcer object"
// @Success 200 {object} object
// @Success 200 {object} object.Enforcer
// @router /delete-enforcer [post]
func (c *ApiController) DeleteEnforcer() {
var enforcer object.Enforcer

View File

@ -26,8 +26,10 @@ type LinkForm struct {
}
// Unlink ...
// @router /unlink [post]
// @Tag Login API
// @Title Unlink
// @router /unlink [post]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) Unlink() {
user, ok := c.RequireSignedInUser()
if !ok {

View File

@ -510,6 +510,7 @@ func (c *ApiController) SetPassword() {
// @Title CheckUserPassword
// @router /check-user-password [post]
// @Tag User API
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) CheckUserPassword() {
var user object.User
err := json.Unmarshal(c.Ctx.Input.RequestBody, &user)
@ -580,6 +581,7 @@ func (c *ApiController) GetUserCount() {
// @Title AddUserKeys
// @router /add-user-keys [post]
// @Tag User API
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) AddUserKeys() {
var user object.User
err := json.Unmarshal(c.Ctx.Input.RequestBody, &user)

View File

@ -39,6 +39,7 @@ const (
// @Title SendVerificationCode
// @Tag Verification API
// @router /send-verification-code [post]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) SendVerificationCode() {
var vform form.VerificationForm
err := c.ParseForm(&vform)
@ -229,6 +230,7 @@ func (c *ApiController) SendVerificationCode() {
// @Title VerifyCaptcha
// @Tag Verification API
// @router /verify-captcha [post]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) VerifyCaptcha() {
var vform form.VerificationForm
err := c.ParseForm(&vform)
@ -271,6 +273,7 @@ func (c *ApiController) VerifyCaptcha() {
// @Tag Account API
// @Title ResetEmailOrPhone
// @router /api/reset-email-or-phone [post]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) ResetEmailOrPhone() {
user, ok := c.RequireSignedInUser()
if !ok {
@ -365,6 +368,7 @@ func (c *ApiController) ResetEmailOrPhone() {
// @Tag Verification API
// @Title VerifyCode
// @router /api/verify-code [post]
// @Success 200 {object} object.Userinfo The Response object
func (c *ApiController) VerifyCode() {
var authForm form.AuthForm
err := json.Unmarshal(c.Ctx.Input.RequestBody, &authForm)

View File

@ -146,7 +146,7 @@ func (c *ApiController) WebAuthnSigninBegin() {
}
// WebAuthnSigninFinish
// @Title WebAuthnSigninBegin
// @Title WebAuthnSigninFinish
// @Tag Login API
// @Description WebAuthn Login Flow 2nd stage
// @Param body body protocol.CredentialAssertionResponse true "authenticator assertion Response"

File diff suppressed because it is too large Load Diff

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: