fix: improve swagger Api docunment (#812)

This commit is contained in:
leoshine 2022-06-21 23:11:29 +08:00 committed by GitHub
parent 8d0e92edef
commit 376bac15dc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 1180 additions and 201 deletions

View File

@ -133,7 +133,7 @@ func (c *ApiController) HandleLoggedIn(application *object.Application, user *ob
// @Param redirectUri query string true "redirect uri"
// @Param scope query string true "scope"
// @Param state query string true "state"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @Success 200 {object} Response The Response object
// @router /get-app-login [get]
func (c *ApiController) GetApplicationLogin() {
clientId := c.Input().Get("clientId")
@ -163,9 +163,16 @@ func setHttpClient(idProvider idp.IdProvider, providerType string) {
// @Title Login
// @Tag Login API
// @Description login
// @Param oAuthParams query string true "oAuth parameters"
// @Param body body RequestForm true "Login information"
// @Success 200 {object} controllers.api_controller.Response The Response object
// @Param clientId query string true clientId
// @Param responseType query string true responseType
// @Param redirectUri query string true redirectUri
// @Param scope query string false scope
// @Param state query string false state
// @Param nonce query string false nonce
// @Param code_challenge_method query string false code_challenge_method
// @Param code_challenge query string false code_challenge
// @Param form body controllers.RequestForm true "Login information"
// @Success 200 {object} Response The Response object
// @router /login [post]
func (c *ApiController) Login() {
resp := &Response{}

View File

@ -18,6 +18,8 @@ import "github.com/casdoor/casdoor/object"
// @Title GetOidcDiscovery
// @Tag OIDC API
// @Description Get Oidc Discovery
// @Success 200 {object} object.OidcDiscovery
// @router /.well-known/openid-configuration [get]
func (c *RootController) GetOidcDiscovery() {
host := c.Ctx.Request.Host
@ -27,6 +29,7 @@ func (c *RootController) GetOidcDiscovery() {
// @Title GetJwks
// @Tag OIDC API
// @Success 200 {object} jose.JSONWebKey
// @router /.well-known/jwks [get]
func (c *RootController) GetJwks() {
jwks, err := object.GetJsonWebKeySet()

View File

@ -26,7 +26,7 @@ import (
// @Description get all records
// @Param pageSize query string true "The size of each page"
// @Param p query string true "The number of the page"
// @Success 200 {array} object.Records The Response object
// @Success 200 {object} object.Record The Response object
// @router /get-records [get]
func (c *ApiController) GetRecords() {
limit := c.Input().Get("pageSize")
@ -50,8 +50,8 @@ func (c *ApiController) GetRecords() {
// @Tag Record API
// @Title GetRecordsByFilter
// @Description get records by filter
// @Param body body object.Records true "filter Record message"
// @Success 200 {array} object.Records The Response object
// @Param filter body string true "filter Record message"
// @Success 200 {object} object.Record The Response object
// @router /get-records-filter [post]
func (c *ApiController) GetRecordsByFilter() {
body := string(c.Ctx.Input.RequestBody)

View File

@ -25,13 +25,26 @@ import (
"github.com/casdoor/casdoor/util"
)
type EmailForm struct {
Title string `json:"title"`
Content string `json:"content"`
Sender string `json:"sender"`
Receivers []string `json:"receivers"`
}
type SmsForm struct {
Content string `json:"content"`
Receivers []string `json:"receivers"`
OrgId string `json:"organizationId"` // e.g. "admin/built-in"
}
// SendEmail
// @Title SendEmail
// @Tag Service API
// @Description This API is not for Casdoor frontend to call, it is for Casdoor SDKs.
// @Param clientId query string true "The clientId of the application"
// @Param clientSecret query string true "The clientSecret of the application"
// @Param body body emailForm true "Details of the email request"
// @Param from body controllers.EmailForm true "Details of the email request"
// @Success 200 {object} Response object
// @router /api/send-email [post]
func (c *ApiController) SendEmail() {
@ -40,12 +53,8 @@ func (c *ApiController) SendEmail() {
return
}
var emailForm struct {
Title string `json:"title"`
Content string `json:"content"`
Sender string `json:"sender"`
Receivers []string `json:"receivers"`
}
var emailForm EmailForm
err := json.Unmarshal(c.Ctx.Input.RequestBody, &emailForm)
if err != nil {
c.ResponseError(err.Error())
@ -86,7 +95,7 @@ func (c *ApiController) SendEmail() {
// @Description This API is not for Casdoor frontend to call, it is for Casdoor SDKs.
// @Param clientId query string true "The clientId of the application"
// @Param clientSecret query string true "The clientSecret of the application"
// @Param body body smsForm true "Details of the sms request"
// @Param from body controllers.SmsForm true "Details of the sms request"
// @Success 200 {object} Response object
// @router /api/send-sms [post]
func (c *ApiController) SendSms() {
@ -95,11 +104,7 @@ func (c *ApiController) SendSms() {
return
}
var smsForm struct {
Content string `json:"content"`
Receivers []string `json:"receivers"`
OrgId string `json:"organizationId"` // e.g. "admin/built-in"
}
var smsForm SmsForm
err := json.Unmarshal(c.Ctx.Input.RequestBody, &smsForm)
if err != nil {
c.ResponseError(err.Error())

View File

@ -56,6 +56,9 @@ func getUploadFileUrl(provider *Provider, fullFilePath string, hasTimestamp bool
// provider.Domain = "http://localhost:8000" or "https://door.casdoor.com"
host = util.UrlJoin(provider.Domain, "/files")
}
if provider.Type == "Azure Blob" {
host = fmt.Sprintf("%s/%s", host, provider.Bucket)
}
fileUrl := util.UrlJoin(host, objectKey)
if hasTimestamp {

File diff suppressed because it is too large Load Diff

View File

@ -12,11 +12,22 @@ paths:
tags:
- OIDC API
operationId: RootController.GetJwks
responses:
"200":
description: ""
schema:
$ref: '#/definitions/jose.JSONWebKey'
/.well-known/openid-configuration:
get:
tags:
- OIDC API
description: Get Oidc Discovery
operationId: RootController.GetOidcDiscovery
responses:
"200":
description: ""
schema:
$ref: '#/definitions/object.OidcDiscovery'
/api/add-application:
post:
tags:
@ -58,6 +69,24 @@ paths:
tags:
- Account API
operationId: ApiController.AddLdap
/api/add-model:
post:
tags:
- Model API
description: add model
operationId: ApiController.AddModel
parameters:
- in: body
name: body
description: The details of the model
required: true
schema:
$ref: '#/definitions/object.Model'
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/add-organization:
post:
tags:
@ -271,11 +300,11 @@ paths:
required: true
type: string
- in: body
name: body
name: from
description: Details of the email request
required: true
schema:
$ref: '#/definitions/emailForm'
$ref: '#/definitions/controllers.EmailForm'
responses:
"200":
description: object
@ -299,11 +328,11 @@ paths:
required: true
type: string
- in: body
name: body
name: from
description: Details of the sms request
required: true
schema:
$ref: '#/definitions/smsForm'
$ref: '#/definitions/controllers.SmsForm'
responses:
"200":
description: object
@ -382,6 +411,24 @@ paths:
tags:
- Account API
operationId: ApiController.DeleteLdap
/api/delete-model:
post:
tags:
- Model API
description: delete model
operationId: ApiController.DeleteModel
parameters:
- in: body
name: body
description: The details of the model
required: true
schema:
$ref: '#/definitions/object.Model'
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/delete-organization:
post:
tags:
@ -578,6 +625,43 @@ paths:
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/get-app-login:
get:
tags:
- Login API
description: get application login
operationId: ApiController.GetApplicationLogin
parameters:
- in: query
name: clientId
description: client id
required: true
type: string
- in: query
name: responseType
description: response type
required: true
type: string
- in: query
name: redirectUri
description: redirect uri
required: true
type: string
- in: query
name: scope
description: scope
required: true
type: string
- in: query
name: state
description: state
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/Response'
/api/get-application:
get:
tags:
@ -700,6 +784,42 @@ paths:
tags:
- Account API
operationId: ApiController.GetLdaps
/api/get-model:
get:
tags:
- Model API
description: get model
operationId: ApiController.GetModel
parameters:
- in: query
name: id
description: The id of the model
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/object.Model'
/api/get-models:
get:
tags:
- Model API
description: get models
operationId: ApiController.GetModels
parameters:
- in: query
name: owner
description: The owner of models
required: true
type: string
responses:
"200":
description: The Response object
schema:
type: array
items:
$ref: '#/definitions/object.Model'
/api/get-organization:
get:
tags:
@ -901,9 +1021,7 @@ paths:
"200":
description: The Response object
schema:
type: array
items:
$ref: '#/definitions/object.Records'
$ref: '#/definitions/object.Record'
/api/get-records-filter:
post:
tags:
@ -912,18 +1030,17 @@ paths:
operationId: ApiController.GetRecordsByFilter
parameters:
- in: body
name: body
name: filter
description: filter Record message
required: true
schema:
$ref: '#/definitions/object.Records'
type: string
type: string
responses:
"200":
description: The Response object
schema:
type: array
items:
$ref: '#/definitions/object.Records'
$ref: '#/definitions/object.Record'
/api/get-resource:
get:
tags:
@ -1216,6 +1333,23 @@ paths:
type: array
items:
$ref: '#/definitions/object.Webhook'
/api/invoice-payment:
post:
tags:
- Payment API
description: invoice payment
operationId: ApiController.InvoicePayment
parameters:
- in: query
name: id
description: The id of the payment
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/login:
post:
tags:
@ -1224,21 +1358,51 @@ paths:
operationId: ApiController.Login
parameters:
- in: query
name: oAuthParams
description: oAuth parameters
name: clientId
description: clientId
required: true
type: string
- in: query
name: responseType
description: responseType
required: true
type: string
- in: query
name: redirectUri
description: redirectUri
required: true
type: string
- in: query
name: scope
description: scope
type: string
- in: query
name: state
description: state
type: string
- in: query
name: nonce
description: nonce
type: string
- in: query
name: code_challenge_method
description: code_challenge_method
type: string
- in: query
name: code_challenge
description: code_challenge
type: string
- in: body
name: body
name: form
description: Login information
required: true
schema:
$ref: '#/definitions/RequestForm'
$ref: '#/definitions/controllers.RequestForm'
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.api_controller.Response'
$ref: '#/definitions/Response'
/api/login/oauth/access_token:
post:
tags:
@ -1424,6 +1588,24 @@ paths:
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/run-syncer:
get:
tags:
- Syncer API
description: run syncer
operationId: ApiController.RunSyncer
parameters:
- in: body
name: body
description: The details of the syncer
required: true
schema:
$ref: '#/definitions/object.Syncer'
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/send-verification-code:
post:
tags:
@ -1493,42 +1675,6 @@ paths:
tags:
- Login API
/api/update-application:
get:
tags:
- Login API
description: get application login
operationId: ApiController.GetApplicationLogin
parameters:
- in: query
name: clientId
description: client id
required: true
type: string
- in: query
name: responseType
description: response type
required: true
type: string
- in: query
name: redirectUri
description: redirect uri
required: true
type: string
- in: query
name: scope
description: scope
required: true
type: string
- in: query
name: state
description: state
required: true
type: string
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.api_controller.Response'
post:
tags:
- Application API
@ -1579,6 +1725,29 @@ paths:
tags:
- Account API
operationId: ApiController.UpdateLdap
/api/update-model:
post:
tags:
- Model API
description: update model
operationId: ApiController.UpdateModel
parameters:
- in: query
name: id
description: The id of the model
required: true
type: string
- in: body
name: body
description: The details of the model
required: true
schema:
$ref: '#/definitions/object.Model'
responses:
"200":
description: The Response object
schema:
$ref: '#/definitions/controllers.Response'
/api/update-organization:
post:
tags:
@ -1830,27 +1999,97 @@ paths:
description: The Response object
schema:
$ref: '#/definitions/object.Userinfo'
/api/verify-captcha:
post:
tags:
- Verification API
operationId: ApiController.VerifyCaptcha
definitions:
2127.0xc00036c600.false:
2200.0xc0003c4b70.false:
title: "false"
type: object
2161.0xc00036c630.false:
2235.0xc0003c4ba0.false:
title: "false"
type: object
RequestForm:
title: RequestForm
type: object
Response:
title: Response
type: object
controllers.EmailForm:
title: EmailForm
type: object
properties:
content:
type: string
receivers:
type: array
items:
type: string
sender:
type: string
title:
type: string
controllers.RequestForm:
title: RequestForm
type: object
properties:
affiliation:
type: string
application:
type: string
autoSignin:
type: boolean
code:
type: string
email:
type: string
emailCode:
type: string
firstName:
type: string
idCard:
type: string
lastName:
type: string
method:
type: string
name:
type: string
organization:
type: string
password:
type: string
phone:
type: string
phoneCode:
type: string
phonePrefix:
type: string
provider:
type: string
redirectUri:
type: string
region:
type: string
relayState:
type: string
samlRequest:
type: string
samlResponse:
type: string
state:
type: string
type:
type: string
username:
type: string
controllers.Response:
title: Response
type: object
properties:
data:
$ref: '#/definitions/2127.0xc00036c600.false'
$ref: '#/definitions/2200.0xc0003c4b70.false'
data2:
$ref: '#/definitions/2161.0xc00036c630.false'
$ref: '#/definitions/2235.0xc0003c4ba0.false'
msg:
type: string
name:
@ -1859,25 +2098,33 @@ definitions:
type: string
sub:
type: string
controllers.api_controller.Response:
title: Response
controllers.SmsForm:
title: SmsForm
type: object
properties:
data:
$ref: '#/definitions/2127.0xc00036c600.false'
data2:
$ref: '#/definitions/2161.0xc00036c630.false'
msg:
content:
type: string
organizationId:
type: string
receivers:
type: array
items:
type: string
jose.JSONWebKey:
title: JSONWebKey
type: object
object.AccountItem:
title: AccountItem
type: object
properties:
modifyRule:
type: string
name:
type: string
status:
viewRule:
type: string
sub:
type: string
emailForm:
title: emailForm
type: object
visible:
type: boolean
object.Adapter:
title: Adapter
type: object
@ -2037,10 +2284,80 @@ definitions:
type: string
username:
type: string
object.Model:
title: Model
type: object
properties:
createdTime:
type: string
displayName:
type: string
isEnabled:
type: boolean
modelText:
type: string
name:
type: string
owner:
type: string
object.OidcDiscovery:
title: OidcDiscovery
type: object
properties:
authorization_endpoint:
type: string
claims_supported:
type: array
items:
type: string
grant_types_supported:
type: array
items:
type: string
id_token_signing_alg_values_supported:
type: array
items:
type: string
introspection_endpoint:
type: string
issuer:
type: string
jwks_uri:
type: string
request_object_signing_alg_values_supported:
type: array
items:
type: string
request_parameter_supported:
type: boolean
response_modes_supported:
type: array
items:
type: string
response_types_supported:
type: array
items:
type: string
scopes_supported:
type: array
items:
type: string
subject_types_supported:
type: array
items:
type: string
token_endpoint:
type: string
userinfo_endpoint:
type: string
object.Organization:
title: Organization
type: object
properties:
accountItems:
type: array
items:
$ref: '#/definitions/object.AccountItem'
createdTime:
type: string
defaultAvatar:
@ -2051,6 +2368,8 @@ definitions:
type: boolean
favicon:
type: string
isProfilePublic:
type: boolean
masterPassword:
type: string
name:
@ -2081,6 +2400,16 @@ definitions:
type: string
displayName:
type: string
invoiceRemark:
type: string
invoiceTaxId:
type: string
invoiceTitle:
type: string
invoiceType:
type: string
invoiceUrl:
type: string
message:
type: string
name:
@ -2091,6 +2420,14 @@ definitions:
type: string
payUrl:
type: string
personEmail:
type: string
personIdCard:
type: string
personName:
type: string
personPhone:
type: string
price:
type: number
format: double
@ -2126,6 +2463,8 @@ definitions:
type: string
isEnabled:
type: boolean
model:
type: string
name:
type: string
owner:
@ -2205,6 +2544,16 @@ definitions:
type: string
createdTime:
type: string
customAuthUrl:
type: string
customLogo:
type: string
customScope:
type: string
customTokenUrl:
type: string
customUserInfoUrl:
type: string
displayName:
type: string
domain:
@ -2264,9 +2613,35 @@ definitions:
type: boolean
provider:
$ref: '#/definitions/object.Provider'
object.Records:
title: Records
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
organization:
type: string
owner:
type: string
requestUri:
type: string
user:
type: string
object.Role:
title: Role
type: object
@ -2442,6 +2817,8 @@ definitions:
type: string
baidu:
type: string
bilibili:
type: string
bio:
type: string
birthday:
@ -2452,10 +2829,14 @@ definitions:
type: string
createdTime:
type: string
custom:
type: string
dingtalk:
type: string
displayName:
type: string
douyin:
type: string
education:
type: string
email:
@ -2521,6 +2902,8 @@ definitions:
type: string
name:
type: string
okta:
type: string
owner:
type: string
password:
@ -2558,6 +2941,8 @@ definitions:
type: string
type:
type: string
unionId:
type: string
updatedTime:
type: string
wechat:
@ -2618,9 +3003,6 @@ definitions:
type: string
url:
type: string
smsForm:
title: smsForm
type: object
xorm.Engine:
title: Engine
type: object