From 3c2aac47e5dea300f08805bed04a7cb8b44eb6b0 Mon Sep 17 00:00:00 2001 From: Xeronith Date: Fri, 30 Sep 2022 11:43:59 +0330 Subject: [PATCH] docs(project): :technologist: update swagger --- greataped/app/docs/docs.go | 63 +++++++++++++++-------------- greataped/app/docs/swagger.json | 63 +++++++++++++++-------------- greataped/app/docs/swagger.yaml | 58 +++++++++++++------------- greataped/app/main.go | 7 +++- greataped/app/models/dto/auth.go | 16 ++++---- greataped/app/models/dto/profile.go | 2 +- greataped/app/routes/profile.go | 2 +- 7 files changed, 112 insertions(+), 99 deletions(-) diff --git a/greataped/app/docs/docs.go b/greataped/app/docs/docs.go index 3359641..884f68a 100644 --- a/greataped/app/docs/docs.go +++ b/greataped/app/docs/docs.go @@ -66,7 +66,7 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/dto.LoginRequest" + "$ref": "#/definitions/LoginRequest" } } ], @@ -74,7 +74,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.LoginResponse" + "$ref": "#/definitions/LoginResponse" } } } @@ -82,6 +82,11 @@ const docTemplate = `{ }, "/api/v1/profile": { "get": { + "security": [ + { + "JWT": [] + } + ], "consumes": [ "application/json" ], @@ -91,21 +96,11 @@ const docTemplate = `{ "tags": [ "User" ], - "parameters": [ - { - "type": "string", - "default": "Bearer \u003cAdd access token here\u003e", - "description": "Insert your access token", - "name": "Authorization", - "in": "header", - "required": true - } - ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.User" + "$ref": "#/definitions/User" } } } @@ -129,7 +124,7 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/dto.SignupRequest" + "$ref": "#/definitions/SignupRequest" } } ], @@ -137,7 +132,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.SignupResponse" + "$ref": "#/definitions/SignupResponse" } } } @@ -161,7 +156,7 @@ const docTemplate = `{ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/dto.VerifyRequest" + "$ref": "#/definitions/VerifyRequest" } } ], @@ -169,7 +164,7 @@ const docTemplate = `{ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.VerifyResponse" + "$ref": "#/definitions/VerifyResponse" } } } @@ -208,7 +203,7 @@ const docTemplate = `{ } }, "definitions": { - "dto.Auth": { + "Auth": { "type": "object", "properties": { "token": { @@ -216,7 +211,7 @@ const docTemplate = `{ } } }, - "dto.LoginRequest": { + "LoginRequest": { "type": "object", "required": [ "email", @@ -231,18 +226,18 @@ const docTemplate = `{ } } }, - "dto.LoginResponse": { + "LoginResponse": { "type": "object", "properties": { "auth": { - "$ref": "#/definitions/dto.Auth" + "$ref": "#/definitions/Auth" }, "user": { - "$ref": "#/definitions/dto.User" + "$ref": "#/definitions/User" } } }, - "dto.SignupRequest": { + "SignupRequest": { "type": "object", "required": [ "email", @@ -261,7 +256,7 @@ const docTemplate = `{ } } }, - "dto.SignupResponse": { + "SignupResponse": { "type": "object", "properties": { "code": { @@ -269,7 +264,7 @@ const docTemplate = `{ } } }, - "dto.User": { + "User": { "type": "object", "properties": { "actor": { @@ -313,7 +308,7 @@ const docTemplate = `{ } } }, - "dto.VerifyRequest": { + "VerifyRequest": { "type": "object", "required": [ "code", @@ -328,17 +323,25 @@ const docTemplate = `{ } } }, - "dto.VerifyResponse": { + "VerifyResponse": { "type": "object", "properties": { "auth": { - "$ref": "#/definitions/dto.Auth" + "$ref": "#/definitions/Auth" }, "user": { - "$ref": "#/definitions/dto.User" + "$ref": "#/definitions/User" } } } + }, + "securityDefinitions": { + "JWT": { + "description": "Example: Bearer {Your JWT Token}", + "type": "apiKey", + "name": "Authorization", + "in": "header" + } } }` @@ -349,7 +352,7 @@ var SwaggerInfo = &swag.Spec{ BasePath: "/", Schemes: []string{}, Title: "GreatApe API", - Description: "GreatApe is a free audio and video social-media platform that can be used via an app. It is a Fediverse technology that supports federation via ActivityPub.", + Description: "GreatApe is a free audio and video social-media platform that can be used via an app.\nIt is a Fediverse technology that supports federation via ActivityPub.", InfoInstanceName: "swagger", SwaggerTemplate: docTemplate, } diff --git a/greataped/app/docs/swagger.json b/greataped/app/docs/swagger.json index 1c53f76..800700b 100644 --- a/greataped/app/docs/swagger.json +++ b/greataped/app/docs/swagger.json @@ -1,7 +1,7 @@ { "swagger": "2.0", "info": { - "description": "GreatApe is a free audio and video social-media platform that can be used via an app. It is a Fediverse technology that supports federation via ActivityPub.", + "description": "GreatApe is a free audio and video social-media platform that can be used via an app.\nIt is a Fediverse technology that supports federation via ActivityPub.", "title": "GreatApe API", "contact": {}, "version": "1.0" @@ -58,7 +58,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/dto.LoginRequest" + "$ref": "#/definitions/LoginRequest" } } ], @@ -66,7 +66,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.LoginResponse" + "$ref": "#/definitions/LoginResponse" } } } @@ -74,6 +74,11 @@ }, "/api/v1/profile": { "get": { + "security": [ + { + "JWT": [] + } + ], "consumes": [ "application/json" ], @@ -83,21 +88,11 @@ "tags": [ "User" ], - "parameters": [ - { - "type": "string", - "default": "Bearer \u003cAdd access token here\u003e", - "description": "Insert your access token", - "name": "Authorization", - "in": "header", - "required": true - } - ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.User" + "$ref": "#/definitions/User" } } } @@ -121,7 +116,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/dto.SignupRequest" + "$ref": "#/definitions/SignupRequest" } } ], @@ -129,7 +124,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.SignupResponse" + "$ref": "#/definitions/SignupResponse" } } } @@ -153,7 +148,7 @@ "in": "body", "required": true, "schema": { - "$ref": "#/definitions/dto.VerifyRequest" + "$ref": "#/definitions/VerifyRequest" } } ], @@ -161,7 +156,7 @@ "200": { "description": "OK", "schema": { - "$ref": "#/definitions/dto.VerifyResponse" + "$ref": "#/definitions/VerifyResponse" } } } @@ -200,7 +195,7 @@ } }, "definitions": { - "dto.Auth": { + "Auth": { "type": "object", "properties": { "token": { @@ -208,7 +203,7 @@ } } }, - "dto.LoginRequest": { + "LoginRequest": { "type": "object", "required": [ "email", @@ -223,18 +218,18 @@ } } }, - "dto.LoginResponse": { + "LoginResponse": { "type": "object", "properties": { "auth": { - "$ref": "#/definitions/dto.Auth" + "$ref": "#/definitions/Auth" }, "user": { - "$ref": "#/definitions/dto.User" + "$ref": "#/definitions/User" } } }, - "dto.SignupRequest": { + "SignupRequest": { "type": "object", "required": [ "email", @@ -253,7 +248,7 @@ } } }, - "dto.SignupResponse": { + "SignupResponse": { "type": "object", "properties": { "code": { @@ -261,7 +256,7 @@ } } }, - "dto.User": { + "User": { "type": "object", "properties": { "actor": { @@ -305,7 +300,7 @@ } } }, - "dto.VerifyRequest": { + "VerifyRequest": { "type": "object", "required": [ "code", @@ -320,16 +315,24 @@ } } }, - "dto.VerifyResponse": { + "VerifyResponse": { "type": "object", "properties": { "auth": { - "$ref": "#/definitions/dto.Auth" + "$ref": "#/definitions/Auth" }, "user": { - "$ref": "#/definitions/dto.User" + "$ref": "#/definitions/User" } } } + }, + "securityDefinitions": { + "JWT": { + "description": "Example: Bearer {Your JWT Token}", + "type": "apiKey", + "name": "Authorization", + "in": "header" + } } } \ No newline at end of file diff --git a/greataped/app/docs/swagger.yaml b/greataped/app/docs/swagger.yaml index ca9eeb0..0c08aa8 100644 --- a/greataped/app/docs/swagger.yaml +++ b/greataped/app/docs/swagger.yaml @@ -1,11 +1,11 @@ basePath: / definitions: - dto.Auth: + Auth: properties: token: type: string type: object - dto.LoginRequest: + LoginRequest: properties: email: type: string @@ -15,14 +15,14 @@ definitions: - email - password type: object - dto.LoginResponse: + LoginResponse: properties: auth: - $ref: '#/definitions/dto.Auth' + $ref: '#/definitions/Auth' user: - $ref: '#/definitions/dto.User' + $ref: '#/definitions/User' type: object - dto.SignupRequest: + SignupRequest: properties: email: type: string @@ -35,12 +35,12 @@ definitions: - password - username type: object - dto.SignupResponse: + SignupResponse: properties: code: type: string type: object - dto.User: + User: properties: actor: type: string @@ -69,7 +69,7 @@ definitions: webfinger: type: string type: object - dto.VerifyRequest: + VerifyRequest: properties: code: type: string @@ -79,17 +79,18 @@ definitions: - code - email type: object - dto.VerifyResponse: + VerifyResponse: properties: auth: - $ref: '#/definitions/dto.Auth' + $ref: '#/definitions/Auth' user: - $ref: '#/definitions/dto.User' + $ref: '#/definitions/User' type: object info: contact: {} - description: GreatApe is a free audio and video social-media platform that can be - used via an app. It is a Fediverse technology that supports federation via ActivityPub. + description: |- + GreatApe is a free audio and video social-media platform that can be used via an app. + It is a Fediverse technology that supports federation via ActivityPub. title: GreatApe API version: "1.0" paths: @@ -124,34 +125,29 @@ paths: name: payload required: true schema: - $ref: '#/definitions/dto.LoginRequest' + $ref: '#/definitions/LoginRequest' produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/dto.LoginResponse' + $ref: '#/definitions/LoginResponse' tags: - Authentication /api/v1/profile: get: consumes: - application/json - parameters: - - default: Bearer - description: Insert your access token - in: header - name: Authorization - required: true - type: string produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/dto.User' + $ref: '#/definitions/User' + security: + - JWT: [] tags: - User /api/v1/signup: @@ -164,14 +160,14 @@ paths: name: payload required: true schema: - $ref: '#/definitions/dto.SignupRequest' + $ref: '#/definitions/SignupRequest' produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/dto.SignupResponse' + $ref: '#/definitions/SignupResponse' tags: - Authentication /api/v1/verify: @@ -184,14 +180,14 @@ paths: name: payload required: true schema: - $ref: '#/definitions/dto.VerifyRequest' + $ref: '#/definitions/VerifyRequest' produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/dto.VerifyResponse' + $ref: '#/definitions/VerifyResponse' tags: - Authentication /u/{username}: @@ -214,4 +210,10 @@ paths: type: object tags: - ActivityPub +securityDefinitions: + JWT: + description: 'Example: Bearer {Your JWT Token}' + in: header + name: Authorization + type: apiKey swagger: "2.0" diff --git a/greataped/app/main.go b/greataped/app/main.go index bca28ab..ff1fdce 100644 --- a/greataped/app/main.go +++ b/greataped/app/main.go @@ -14,8 +14,13 @@ import ( // @title GreatApe API // @version 1.0 -// @description GreatApe is a free audio and video social-media platform that can be used via an app. It is a Fediverse technology that supports federation via ActivityPub. +// @description GreatApe is a free audio and video social-media platform that can be used via an app. +// @description It is a Fediverse technology that supports federation via ActivityPub. // @BasePath / +// @securityDefinitions.apiKey JWT +// @in header +// @name Authorization +// @description Example: Bearer {Your JWT Token} func main() { if config.IsProduction() { docs.SwaggerInfo.Host = config.DOMAIN diff --git a/greataped/app/models/dto/auth.go b/greataped/app/models/dto/auth.go index a7a7649..37c3bde 100644 --- a/greataped/app/models/dto/auth.go +++ b/greataped/app/models/dto/auth.go @@ -3,32 +3,32 @@ package dto type LoginRequest struct { Email string `json:"email" validate:"required,email"` Password string `json:"password" validate:"required,password"` -} +} // @name LoginRequest type LoginResponse struct { User User `json:"user"` Auth Auth `json:"auth"` -} +} // @name LoginResponse type SignupRequest struct { Email string `json:"email" validate:"required,email"` Username string `json:"username" validate:"required,username"` Password string `json:"password" validate:"required,password"` -} +} // @name SignupRequest type SignupResponse struct { Code string `json:"code"` -} +} // @name SignupResponse type VerifyRequest struct { Email string `json:"email" validate:"required,email"` Code string `json:"code" validate:"required"` -} +} // @name VerifyRequest type VerifyResponse struct { User User `json:"user"` Auth Auth `json:"auth"` -} +} // @name VerifyResponse type User struct { ID uint `json:"id"` @@ -45,8 +45,8 @@ type User struct { Actor string `json:"actor,omitempty"` Webfinger string `json:"webfinger,omitempty"` PrivateProfile bool `json:"private_profile"` -} +} // @name User type Auth struct { Token string `json:"token"` -} +} // @name Auth diff --git a/greataped/app/models/dto/profile.go b/greataped/app/models/dto/profile.go index e49f374..bee44f0 100644 --- a/greataped/app/models/dto/profile.go +++ b/greataped/app/models/dto/profile.go @@ -7,4 +7,4 @@ type ProfileRequest struct { Avatar string `json:"avatar"` Banner string `json:"banner"` PrivateProfile bool `json:"private_profile"` -} +} // @name ProfileRequest diff --git a/greataped/app/routes/profile.go b/greataped/app/routes/profile.go index 437fe3b..63eb7e0 100644 --- a/greataped/app/routes/profile.go +++ b/greataped/app/routes/profile.go @@ -21,7 +21,7 @@ var Profile = route.New(HttpGet, "/profile", func(x IContext) error { // @Tags User // @Accept json // @Produce json -// @Param Authorization header string true "Insert your access token" default(Bearer ) +// @Security JWT // @Success 200 {object} dto.User // @Router /api/v1/profile [get] func _() {}