From 24f897e907aeb09b64ab22bff253db7cf9843442 Mon Sep 17 00:00:00 2001 From: Lilleman Date: Tue, 22 Jun 2021 23:49:11 +0200 Subject: [PATCH] Added more proper documentation --- src/docs/docs.go | 213 ++++++++++++++++++++++++++++++++++++------ src/docs/swagger.json | 212 +++++++++++++++++++++++++++++++++++------ src/docs/swagger.yaml | 165 ++++++++++++++++++++++++++------ src/handlers/get.go | 14 +-- src/handlers/post.go | 68 ++++++++------ src/main.go | 3 +- 6 files changed, 552 insertions(+), 123 deletions(-) diff --git a/src/docs/docs.go b/src/docs/docs.go index b6e7e27..3adaf36 100644 --- a/src/docs/docs.go +++ b/src/docs/docs.go @@ -20,7 +20,7 @@ var doc = `{ "title": "{{.Title}}", "contact": { "name": "Power Plan", - "url": "https://http://pwrpln.com/", + "url": "https://pwrpln.com/", "email": "lilleman@larvit.se" }, "license": { @@ -33,7 +33,7 @@ var doc = `{ "paths": { "/account": { "post": { - "description": "Create an account", + "description": "Requires Authorization-header with role \"admin\".\nExample: Authorization: bearer xxx\nWhere \"xxx\" is a valid JWT token", "consumes": [ "application/json" ], @@ -42,6 +42,17 @@ var doc = `{ ], "summary": "Create an account", "operationId": "account-create", + "parameters": [ + { + "description": "Account object to be written to database", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/handlers.AccountInput" + } + } + ], "responses": { "200": { "description": "OK", @@ -52,25 +63,37 @@ var doc = `{ "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -78,14 +101,14 @@ var doc = `{ }, "/account/{id}": { "get": { - "description": "Get account", + "description": "Requires Authorization-header with either role \"admin\" or with a matching account id.\nExample: Authorization: bearer xxx\nWhere \"xxx\" is a valid JWT token", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "summary": "Get account", + "summary": "Get account by id", "operationId": "get-account-by-id", "parameters": [ { @@ -106,25 +129,37 @@ var doc = `{ "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -141,35 +176,58 @@ var doc = `{ ], "summary": "Authenticate account by API Key", "operationId": "auth-account-by-api-key", + "parameters": [ + { + "description": "API Key as a string in JSON format (just encapsulate the string with \\", + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/db.Account" + "$ref": "#/definitions/handlers.ResToken" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -186,35 +244,58 @@ var doc = `{ ], "summary": "Authenticate account by Password", "operationId": "auth-account-by-password", + "parameters": [ + { + "description": "Name and password to auth by", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/handlers.AuthInput" + } + } + ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/db.Account" + "$ref": "#/definitions/handlers.ResToken" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -231,35 +312,58 @@ var doc = `{ ], "summary": "Renew token", "operationId": "renew-token", + "parameters": [ + { + "description": "Renewal token as a string in JSON format (just encapsulate the string with \\", + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/db.Account" + "$ref": "#/definitions/handlers.ResToken" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -290,6 +394,20 @@ var doc = `{ } } }, + "db.AccountCreateInputFields": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "db.CreatedAccount": { "type": "object", "properties": { @@ -304,6 +422,34 @@ var doc = `{ } } }, + "handlers.AccountInput": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "items": { + "$ref": "#/definitions/db.AccountCreateInputFields" + } + }, + "name": { + "type": "string" + }, + "password": { + "type": "string" + } + } + }, + "handlers.AuthInput": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "password": { + "type": "string" + } + } + }, "handlers.ResJSONError": { "type": "object", "properties": { @@ -314,6 +460,17 @@ var doc = `{ "type": "string" } } + }, + "handlers.ResToken": { + "type": "object", + "properties": { + "jwt": { + "type": "string" + }, + "renewalToken": { + "type": "string" + } + } } } }` @@ -330,7 +487,7 @@ type swaggerInfo struct { // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = swaggerInfo{ Version: "0.1", - Host: "localhost:3000", + Host: "", BasePath: "/", Schemes: []string{}, Title: "JWT Auth API", diff --git a/src/docs/swagger.json b/src/docs/swagger.json index c4b76c9..8c6c1ee 100644 --- a/src/docs/swagger.json +++ b/src/docs/swagger.json @@ -5,7 +5,7 @@ "title": "JWT Auth API", "contact": { "name": "Power Plan", - "url": "https://http://pwrpln.com/", + "url": "https://pwrpln.com/", "email": "lilleman@larvit.se" }, "license": { @@ -13,12 +13,11 @@ }, "version": "0.1" }, - "host": "localhost:3000", "basePath": "/", "paths": { "/account": { "post": { - "description": "Create an account", + "description": "Requires Authorization-header with role \"admin\".\nExample: Authorization: bearer xxx\nWhere \"xxx\" is a valid JWT token", "consumes": [ "application/json" ], @@ -27,6 +26,17 @@ ], "summary": "Create an account", "operationId": "account-create", + "parameters": [ + { + "description": "Account object to be written to database", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/handlers.AccountInput" + } + } + ], "responses": { "200": { "description": "OK", @@ -37,25 +47,37 @@ "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -63,14 +85,14 @@ }, "/account/{id}": { "get": { - "description": "Get account", + "description": "Requires Authorization-header with either role \"admin\" or with a matching account id.\nExample: Authorization: bearer xxx\nWhere \"xxx\" is a valid JWT token", "consumes": [ "application/json" ], "produces": [ "application/json" ], - "summary": "Get account", + "summary": "Get account by id", "operationId": "get-account-by-id", "parameters": [ { @@ -91,25 +113,37 @@ "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -126,35 +160,58 @@ ], "summary": "Authenticate account by API Key", "operationId": "auth-account-by-api-key", + "parameters": [ + { + "description": "API Key as a string in JSON format (just encapsulate the string with \\", + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/db.Account" + "$ref": "#/definitions/handlers.ResToken" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -171,35 +228,58 @@ ], "summary": "Authenticate account by Password", "operationId": "auth-account-by-password", + "parameters": [ + { + "description": "Name and password to auth by", + "name": "body", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/handlers.AuthInput" + } + } + ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/db.Account" + "$ref": "#/definitions/handlers.ResToken" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -216,35 +296,58 @@ ], "summary": "Renew token", "operationId": "renew-token", + "parameters": [ + { + "description": "Renewal token as a string in JSON format (just encapsulate the string with \\", + "name": "body", + "in": "body", + "required": true, + "schema": { + "type": "string" + } + } + ], "responses": { "200": { "description": "OK", "schema": { - "$ref": "#/definitions/db.Account" + "$ref": "#/definitions/handlers.ResToken" } }, "401": { "description": "Unauthorized", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "403": { "description": "Forbidden", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "415": { "description": "Unsupported Media Type", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } }, "500": { "description": "Internal Server Error", "schema": { - "$ref": "#/definitions/handlers.ResJSONError" + "type": "array", + "items": { + "$ref": "#/definitions/handlers.ResJSONError" + } } } } @@ -275,6 +378,20 @@ } } }, + "db.AccountCreateInputFields": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, "db.CreatedAccount": { "type": "object", "properties": { @@ -289,6 +406,34 @@ } } }, + "handlers.AccountInput": { + "type": "object", + "properties": { + "fields": { + "type": "array", + "items": { + "$ref": "#/definitions/db.AccountCreateInputFields" + } + }, + "name": { + "type": "string" + }, + "password": { + "type": "string" + } + } + }, + "handlers.AuthInput": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "password": { + "type": "string" + } + } + }, "handlers.ResJSONError": { "type": "object", "properties": { @@ -299,6 +444,17 @@ "type": "string" } } + }, + "handlers.ResToken": { + "type": "object", + "properties": { + "jwt": { + "type": "string" + }, + "renewalToken": { + "type": "string" + } + } } } } \ No newline at end of file diff --git a/src/docs/swagger.yaml b/src/docs/swagger.yaml index 96cc56e..5310f06 100644 --- a/src/docs/swagger.yaml +++ b/src/docs/swagger.yaml @@ -15,6 +15,15 @@ definitions: name: type: string type: object + db.AccountCreateInputFields: + properties: + name: + type: string + values: + items: + type: string + type: array + type: object db.CreatedAccount: properties: apiKey: @@ -24,6 +33,24 @@ definitions: name: type: string type: object + handlers.AccountInput: + properties: + fields: + items: + $ref: '#/definitions/db.AccountCreateInputFields' + type: array + name: + type: string + password: + type: string + type: object + handlers.AuthInput: + properties: + name: + type: string + password: + type: string + type: object handlers.ResJSONError: properties: error: @@ -31,12 +58,18 @@ definitions: field: type: string type: object -host: localhost:3000 + handlers.ResToken: + properties: + jwt: + type: string + renewalToken: + type: string + type: object info: contact: email: lilleman@larvit.se name: Power Plan - url: https://http://pwrpln.com/ + url: https://pwrpln.com/ description: This is a tiny http API for auth. Register accounts, auth with api-key or name/password, renew JWT tokens... license: @@ -48,8 +81,18 @@ paths: post: consumes: - application/json - description: Create an account + description: |- + Requires Authorization-header with role "admin". + Example: Authorization: bearer xxx + Where "xxx" is a valid JWT token operationId: account-create + parameters: + - description: Account object to be written to database + in: body + name: body + required: true + schema: + $ref: '#/definitions/handlers.AccountInput' produces: - application/json responses: @@ -60,25 +103,36 @@ paths: "401": description: Unauthorized schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "403": description: Forbidden schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "415": description: Unsupported Media Type schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "500": description: Internal Server Error schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array summary: Create an account /account/{id}: get: consumes: - application/json - description: Get account + description: |- + Requires Authorization-header with either role "admin" or with a matching account id. + Example: Authorization: bearer xxx + Where "xxx" is a valid JWT token operationId: get-account-by-id parameters: - description: Account ID @@ -96,49 +150,73 @@ paths: "401": description: Unauthorized schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "403": description: Forbidden schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "415": description: Unsupported Media Type schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "500": description: Internal Server Error schema: - $ref: '#/definitions/handlers.ResJSONError' - summary: Get account + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array + summary: Get account by id /auth/api-key: post: consumes: - application/json description: Authenticate account by API Key operationId: auth-account-by-api-key + parameters: + - description: API Key as a string in JSON format (just encapsulate the string + with \ + in: body + name: body + required: true + schema: + type: string produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/db.Account' + $ref: '#/definitions/handlers.ResToken' "401": description: Unauthorized schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "403": description: Forbidden schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "415": description: Unsupported Media Type schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "500": description: Internal Server Error schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array summary: Authenticate account by API Key /auth/password: post: @@ -146,29 +224,44 @@ paths: - application/json description: Authenticate account by Password operationId: auth-account-by-password + parameters: + - description: Name and password to auth by + in: body + name: body + required: true + schema: + $ref: '#/definitions/handlers.AuthInput' produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/db.Account' + $ref: '#/definitions/handlers.ResToken' "401": description: Unauthorized schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "403": description: Forbidden schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "415": description: Unsupported Media Type schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "500": description: Internal Server Error schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array summary: Authenticate account by Password /renew-token: post: @@ -176,28 +269,44 @@ paths: - application/json description: Renew token operationId: renew-token + parameters: + - description: Renewal token as a string in JSON format (just encapsulate the + string with \ + in: body + name: body + required: true + schema: + type: string produces: - application/json responses: "200": description: OK schema: - $ref: '#/definitions/db.Account' + $ref: '#/definitions/handlers.ResToken' "401": description: Unauthorized schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "403": description: Forbidden schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "415": description: Unsupported Media Type schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array "500": description: Internal Server Error schema: - $ref: '#/definitions/handlers.ResJSONError' + items: + $ref: '#/definitions/handlers.ResJSONError' + type: array summary: Renew token swagger: "2.0" diff --git a/src/handlers/get.go b/src/handlers/get.go index 1c4cefe..fb08008 100644 --- a/src/handlers/get.go +++ b/src/handlers/get.go @@ -5,17 +5,19 @@ import ( ) // AccountGet godoc -// @Summary Get account -// @Description Get account +// @Summary Get account by id +// @Description Requires Authorization-header with either role "admin" or with a matching account id. +// @Description Example: Authorization: bearer xxx +// @Description Where "xxx" is a valid JWT token // @ID get-account-by-id // @Accept json // @Produce json // @Param id path string true "Account ID" // @Success 200 {object} db.Account -// @Failure 401 {object} ResJSONError -// @Failure 403 {object} ResJSONError -// @Failure 415 {object} ResJSONError -// @Failure 500 {object} ResJSONError +// @Failure 401 {object} []ResJSONError +// @Failure 403 {object} []ResJSONError +// @Failure 415 {object} []ResJSONError +// @Failure 500 {object} []ResJSONError // @Router /account/{id} [get] func (h Handlers) AccountGet(c *fiber.Ctx) error { accountID := c.Params("accountID") diff --git a/src/handlers/post.go b/src/handlers/post.go index b6b33fd..b13da5c 100644 --- a/src/handlers/post.go +++ b/src/handlers/post.go @@ -9,17 +9,31 @@ import ( "gitlab.larvit.se/power-plan/auth/src/utils" ) +type AccountInput struct { + Name string `json:"name"` + Password string `json:"password"` + Fields []db.AccountCreateInputFields `json:"fields"` +} + +type AuthInput struct { + Name string `json:"name"` + Password string `json:"password"` +} + // AccountCreate godoc // @Summary Create an account -// @Description Create an account +// @Description Requires Authorization-header with role "admin". +// @Description Example: Authorization: bearer xxx +// @Description Where "xxx" is a valid JWT token // @ID account-create // @Accept json // @Produce json +// @Param body body AccountInput true "Account object to be written to database" // @Success 200 {object} db.CreatedAccount -// @Failure 401 {object} ResJSONError -// @Failure 403 {object} ResJSONError -// @Failure 415 {object} ResJSONError -// @Failure 500 {object} ResJSONError +// @Failure 401 {object} []ResJSONError +// @Failure 403 {object} []ResJSONError +// @Failure 415 {object} []ResJSONError +// @Failure 500 {object} []ResJSONError // @Router /account [post] func (h Handlers) AccountCreate(c *fiber.Ctx) error { authErr := h.RequireAdminRole(c) @@ -27,12 +41,6 @@ func (h Handlers) AccountCreate(c *fiber.Ctx) error { return c.Status(403).JSON([]ResJSONError{{Error: authErr.Error()}}) } - type AccountInput struct { - Name string `json:"name"` - Password string `json:"password"` - Fields []db.AccountCreateInputFields `json:"fields"` - } - accountInput := new(AccountInput) if err := c.BodyParser(accountInput); err != nil { @@ -85,11 +93,12 @@ func (h Handlers) AccountCreate(c *fiber.Ctx) error { // @ID auth-account-by-api-key // @Accept json // @Produce json -// @Success 200 {object} db.Account -// @Failure 401 {object} ResJSONError -// @Failure 403 {object} ResJSONError -// @Failure 415 {object} ResJSONError -// @Failure 500 {object} ResJSONError +// @Param body body string true "API Key as a string in JSON format (just encapsulate the string with \" and you're fine)" +// @Success 200 {object} ResToken +// @Failure 401 {object} []ResJSONError +// @Failure 403 {object} []ResJSONError +// @Failure 415 {object} []ResJSONError +// @Failure 500 {object} []ResJSONError // @Router /auth/api-key [post] func (h Handlers) AccountAuthAPIKey(c *fiber.Ctx) error { inputAPIKey := string(c.Request().Body()) @@ -113,18 +122,14 @@ func (h Handlers) AccountAuthAPIKey(c *fiber.Ctx) error { // @ID auth-account-by-password // @Accept json // @Produce json -// @Success 200 {object} db.Account -// @Failure 401 {object} ResJSONError -// @Failure 403 {object} ResJSONError -// @Failure 415 {object} ResJSONError -// @Failure 500 {object} ResJSONError +// @Param body body AuthInput true "Name and password to auth by" +// @Success 200 {object} ResToken +// @Failure 401 {object} []ResJSONError +// @Failure 403 {object} []ResJSONError +// @Failure 415 {object} []ResJSONError +// @Failure 500 {object} []ResJSONError // @Router /auth/password [post] func (h Handlers) AccountAuthPassword(c *fiber.Ctx) error { - type AuthInput struct { - Name string `json:"name"` - Password string `json:"password"` - } - authInput := new(AuthInput) if err := c.BodyParser(authInput); err != nil { return c.Status(400).JSON([]ResJSONError{{Error: err.Error()}}) @@ -152,11 +157,12 @@ func (h Handlers) AccountAuthPassword(c *fiber.Ctx) error { // @ID renew-token // @Accept json // @Produce json -// @Success 200 {object} db.Account -// @Failure 401 {object} ResJSONError -// @Failure 403 {object} ResJSONError -// @Failure 415 {object} ResJSONError -// @Failure 500 {object} ResJSONError +// @Param body body string true "Renewal token as a string in JSON format (just encapsulate the string with \" and you're fine)" +// @Success 200 {object} ResToken +// @Failure 401 {object} []ResJSONError +// @Failure 403 {object} []ResJSONError +// @Failure 415 {object} []ResJSONError +// @Failure 500 {object} []ResJSONError // @Router /renew-token [post] func (h Handlers) RenewToken(c *fiber.Ctx) error { inputToken := string(c.Request().Body()) diff --git a/src/main.go b/src/main.go index d558a33..1394458 100644 --- a/src/main.go +++ b/src/main.go @@ -44,12 +44,11 @@ func createAdminAccount(Db db.Db, log *zap.SugaredLogger) { // @description This is a tiny http API for auth. Register accounts, auth with api-key or name/password, renew JWT tokens... // @contact.name Power Plan -// @contact.url https://http://pwrpln.com/ +// @contact.url https://pwrpln.com/ // @contact.email lilleman@larvit.se // @license.name MIT -// @host localhost:3000 // @BasePath / func main() { log := utils.GetLog()