fix: improve swagger Api docunment (#812)

controllers/auth.go

@@ -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 clientId        query    string  true clientId
-// @Param   body    body   RequestForm  true        "Login information"
+// @Param responseType    query    string  true responseType
-// @Success 200 {object} controllers.api_controller.Response The Response object
+// @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{}

controllers/oidc_discovery.go

@@ -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()

controllers/record.go

@@ -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"
+// @Param   filter  body string     true  "filter Record message"
-// @Success 200 {array} object.Records The Response object
+// @Success 200 {object} object.Record The Response object
 // @router /get-records-filter [post]
 func (c *ApiController) GetRecordsByFilter() {
 	body := string(c.Ctx.Input.RequestBody)

controllers/service.go

@@ -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 {
+	var emailForm EmailForm
-		Title     string   `json:"title"`
+
-		Content   string   `json:"content"`
-		Sender    string   `json:"sender"`
-		Receivers []string `json:"receivers"`
-	}
 	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 {
+	var smsForm SmsForm
-		Content   string   `json:"content"`
-		Receivers []string `json:"receivers"`
-		OrgId     string   `json:"organizationId"` // e.g. "admin/built-in"
-	}
 	err := json.Unmarshal(c.Ctx.Input.RequestBody, &smsForm)
 	if err != nil {
 		c.ResponseError(err.Error())

object/storage.go

@@ -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 {

swagger/swagger.yml

@@ -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
+            $ref: '#/definitions/object.Record'
-            items:
-              $ref: '#/definitions/object.Records'
   /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
+            $ref: '#/definitions/object.Record'
-            items:
-              $ref: '#/definitions/object.Records'
   /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
+        name: clientId
-        description: oAuth parameters
+        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:
+  controllers.SmsForm:
-    title: Response
+    title: SmsForm
     type: object
     properties:
-      data:
+      content:
-        $ref: '#/definitions/2127.0xc00036c600.false'
+        type: string
-      data2:
+      organizationId:
-        $ref: '#/definitions/2161.0xc00036c630.false'
+        type: string
-      msg:
+      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:
+      visible:
-        type: string
+        type: boolean
-  emailForm:
-    title: emailForm
-    type: object
   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:
+  object.Record:
-    title: Records
+    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