fix: improve swagger Api docunment (#812)

2025-07-03 04:10:20 +08:00 · 2022-06-21 23:11:29 +08:00
parent 8d0e92edef
commit 376bac15dc
7 changed files with 1180 additions and 201 deletions
--- a/swagger/swagger.yml
+++ b/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
-            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