From c3967dd2d6eb0842d0eb174418465b73144020df Mon Sep 17 00:00:00 2001 From: amir Date: Thu, 27 Jun 2024 13:21:19 +0900 Subject: [PATCH] doc: update apis --- static/apis/telar-web/actions.json | 2 +- static/apis/telar-web/actions.yaml | 2 +- static/apis/telar-web/auth.json | 194 ++++++++++++----------------- static/apis/telar-web/auth.yaml | 142 +++++++++------------ 4 files changed, 142 insertions(+), 198 deletions(-) diff --git a/static/apis/telar-web/actions.json b/static/apis/telar-web/actions.json index 1cf91ac..032443a 100644 --- a/static/apis/telar-web/actions.json +++ b/static/apis/telar-web/actions.json @@ -14,7 +14,7 @@ }, "version": "1.0" }, - "host": "social.telar.dev", + "host": "social.faas.telar.dev", "basePath": "/actions", "paths": { "/dispatch/{roomId}": { diff --git a/static/apis/telar-web/actions.yaml b/static/apis/telar-web/actions.yaml index 12e5983..1572852 100644 --- a/static/apis/telar-web/actions.yaml +++ b/static/apis/telar-web/actions.yaml @@ -47,7 +47,7 @@ definitions: error: $ref: '#/definitions/utils.ErrorCodeMessage' type: object -host: social.telar.dev +host: social.faas.telar.dev info: contact: email: dev@telar.dev diff --git a/static/apis/telar-web/auth.json b/static/apis/telar-web/auth.json index 4e2a455..6b9a251 100644 --- a/static/apis/telar-web/auth.json +++ b/static/apis/telar-web/auth.json @@ -17,98 +17,6 @@ "host": "social.faas.telar.dev", "basePath": "/auth", "paths": { - "/": { - "get": { - "description": "Renders the login page for Telar Social", - "produces": [ - "text/html" - ], - "tags": [ - "auth" - ], - "summary": "Login page", - "responses": { - "200": { - "description": "Login page HTML", - "schema": { - "type": "string" - } - } - } - }, - "post": { - "description": "Authenticates a user with Telar Social credentials", - "consumes": [ - "application/x-www-form-urlencoded" - ], - "produces": [ - "application/json" - ], - "tags": [ - "auth" - ], - "summary": "Login with Telar Social", - "parameters": [ - { - "type": "string", - "description": "Username", - "name": "username", - "in": "formData", - "required": true - }, - { - "type": "string", - "description": "Password", - "name": "password", - "in": "formData", - "required": true - }, - { - "type": "string", - "description": "Response Type", - "name": "responseType", - "in": "formData" - }, - { - "type": "string", - "description": "State", - "name": "state", - "in": "formData" - } - ], - "responses": { - "200": { - "description": "User profile and access token", - "schema": { - "type": "object", - "properties": { - "accessToken": { - "type": "string" - }, - "redirect": { - "type": "string" - }, - "user": { - "$ref": "#/definitions/models.UserProfileModel" - } - } - } - }, - "400": { - "description": "Bad request", - "schema": { - "$ref": "#/definitions/utils.TelarError" - } - }, - "500": { - "description": "Internal server error", - "schema": { - "$ref": "#/definitions/utils.TelarError" - } - } - } - } - }, "/admin/check": { "post": { "description": "handler to check whether admin user registered", @@ -255,9 +163,27 @@ } } }, - "/auth/login/telar/spa": { + "/login": { + "get": { + "description": "Renders the login page for Telar Social", + "produces": [ + "text/html" + ], + "tags": [ + "auth" + ], + "summary": "Login page", + "responses": { + "200": { + "description": "Login page HTML", + "schema": { + "type": "string" + } + } + } + }, "post": { - "description": "Authenticates a user with Telar Social credentials for Single Page Applications", + "description": "Authenticates a user with Telar Social credentials", "consumes": [ "application/x-www-form-urlencoded" ], @@ -267,7 +193,7 @@ "tags": [ "auth" ], - "summary": "Login with Telar Social (SPA)", + "summary": "Login with Telar Social", "parameters": [ { "type": "string", @@ -329,7 +255,7 @@ } } }, - "/github": { + "/login/github": { "get": { "description": "Redirects the user to GitHub for authentication", "produces": [ @@ -349,7 +275,7 @@ } } }, - "/google": { + "/login/google": { "get": { "description": "Redirects the user to Google for authentication", "produces": [ @@ -575,39 +501,77 @@ } } }, - "/signup": { + "/signup/token": { "post": { - "description": "return a token to verify user signup process", + "description": "Handles the generation of a signup token for email or phone verification.", + "consumes": [ + "application/json" + ], "produces": [ "application/json" ], - "summary": "create a signup token", + "tags": [ + "auth" + ], + "summary": "Sign up token generation", + "parameters": [ + { + "type": "string", + "description": "Full name of the user", + "name": "fullName", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Email address of the user", + "name": "email", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Password for the new user account", + "name": "newPassword", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Type of verification (email or phone)", + "name": "verifyType", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Google reCAPTCHA response token", + "name": "g-recaptcha-response", + "in": "formData", + "required": true + }, + { + "type": "string", + "description": "Response type indicating the desired response format (default or spa)", + "name": "responseType", + "in": "formData" + } + ], "responses": { "200": { - "description": "OK", - "schema": { - "type": "object", - "properties": { - "token": { - "type": "string" - } - } - } - }, - "400": { - "description": "Bad Request", + "description": "Returns a JSON object containing the generated token if responseType is 'spa', or renders a verification page otherwise.", "schema": { "$ref": "#/definitions/utils.TelarError" } }, - "404": { - "description": "Not Found", + "400": { + "description": "Returns a JSON object describing the missing or invalid parameters.", "schema": { "$ref": "#/definitions/utils.TelarError" } }, "500": { - "description": "Internal Server Error", + "description": "Returns a JSON object indicating an internal server error, such as failure to create a user or verify captcha.", "schema": { "$ref": "#/definitions/utils.TelarError" } diff --git a/static/apis/telar-web/auth.yaml b/static/apis/telar-web/auth.yaml index 410a215..50580ec 100644 --- a/static/apis/telar-web/auth.yaml +++ b/static/apis/telar-web/auth.yaml @@ -106,67 +106,6 @@ info: title: Auth micro API version: "1.0" paths: - /: - get: - description: Renders the login page for Telar Social - produces: - - text/html - responses: - "200": - description: Login page HTML - schema: - type: string - summary: Login page - tags: - - auth - post: - consumes: - - application/x-www-form-urlencoded - description: Authenticates a user with Telar Social credentials - parameters: - - description: Username - in: formData - name: username - required: true - type: string - - description: Password - in: formData - name: password - required: true - type: string - - description: Response Type - in: formData - name: responseType - type: string - - description: State - in: formData - name: state - type: string - produces: - - application/json - responses: - "200": - description: User profile and access token - schema: - properties: - accessToken: - type: string - redirect: - type: string - user: - $ref: '#/definitions/models.UserProfileModel' - type: object - "400": - description: Bad request - schema: - $ref: '#/definitions/utils.TelarError' - "500": - description: Internal server error - schema: - $ref: '#/definitions/utils.TelarError' - summary: Login with Telar Social - tags: - - auth /admin/check: post: description: handler to check whether admin user registered @@ -262,12 +201,23 @@ paths: schema: $ref: '#/definitions/utils.TelarError' summary: signup the admin user - /auth/login/telar/spa: + /login: + get: + description: Renders the login page for Telar Social + produces: + - text/html + responses: + "200": + description: Login page HTML + schema: + type: string + summary: Login page + tags: + - auth post: consumes: - application/x-www-form-urlencoded - description: Authenticates a user with Telar Social credentials for Single Page - Applications + description: Authenticates a user with Telar Social credentials parameters: - description: Username in: formData @@ -309,10 +259,10 @@ paths: description: Internal server error schema: $ref: '#/definitions/utils.TelarError' - summary: Login with Telar Social (SPA) + summary: Login with Telar Social tags: - auth - /github: + /login/github: get: description: Redirects the user to GitHub for authentication produces: @@ -325,7 +275,7 @@ paths: summary: Login with GitHub tags: - auth - /google: + /login/google: get: description: Redirects the user to Google for authentication produces: @@ -475,32 +425,62 @@ paths: schema: $ref: '#/definitions/utils.TelarError' summary: reset user password - /signup: + /signup/token: post: - description: return a token to verify user signup process + consumes: + - application/json + description: Handles the generation of a signup token for email or phone verification. + parameters: + - description: Full name of the user + in: formData + name: fullName + required: true + type: string + - description: Email address of the user + in: formData + name: email + required: true + type: string + - description: Password for the new user account + in: formData + name: newPassword + required: true + type: string + - description: Type of verification (email or phone) + in: formData + name: verifyType + required: true + type: string + - description: Google reCAPTCHA response token + in: formData + name: g-recaptcha-response + required: true + type: string + - description: Response type indicating the desired response format (default + or spa) + in: formData + name: responseType + type: string produces: - application/json responses: "200": - description: OK - schema: - properties: - token: - type: string - type: object - "400": - description: Bad Request + description: Returns a JSON object containing the generated token if responseType + is 'spa', or renders a verification page otherwise. schema: $ref: '#/definitions/utils.TelarError' - "404": - description: Not Found + "400": + description: Returns a JSON object describing the missing or invalid parameters. schema: $ref: '#/definitions/utils.TelarError' "500": - description: Internal Server Error + description: Returns a JSON object indicating an internal server error, + such as failure to create a user or verify captcha. schema: $ref: '#/definitions/utils.TelarError' - summary: create a signup token + summary: Sign up token generation + tags: + - auth /signup/verify: post: consumes: