go/golang-saas-starter-kit
1
0
Fork 0
mirror of https://github.com/raseels-repos/golang-saas-starter-kit.git synced 2025-06-17 00:17:59 +02:00
Code Issues Releases Activity

completed API from signup to auth token with swagger UI.

Browse Source
This commit is contained in:
Lee Brown
2019-06-25 06:25:55 -08:00
parent 2fbda74a73
commit 8328cf525b
15 changed files with 443 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
example-project/cmd/web-api/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
local.env

123
example-project/cmd/web-api/README.md
View File

@ -25,6 +25,129 @@ To build using the docker file, need to be in the project root directory. `Docke
docker build -f cmd/web-api/Dockerfile -t saas-web-api .
```
## Getting Started
1. Ensure postgres is running.
Navigate to the project root where `docker-compose.yaml` exists. There is only
one `docker-compose.yaml` file that is shared between all services.
*Start Postgres.*
```bash
docker-compose up -d postgres
```
2. Set env variables.
*Copy the sample file to make your own copy.*
```bash
cp sample.env local.env
```
*Make any changes to your copy of the file if necessary and then add them to your env.
```bash
source local.env
```
3. Start the web-api service.
*Invoke main.go directly or use `go build .`*
```bash
go run main.go
```
4. Open the Swagger UI.
Navigate your browser to [http://localhost:3000/swagger](http://localhost:3000/swagger).
5. Signup a new account.
Find the `signup` endpoint in the Swagger UI.
Click `Try it out`. Example data has been prepopulated
to generate a valid POST request.
```json
{
"account": {
"address1": "221 Tatitlek Ave",
"address2": "Box #1832",
"city": "Valdez",
"country": "USA",
"name": "Company 895ff280-5ed9-4b09-b7bc-86ab0f0951d4",
"region": "AK",
"timezone": "America/Anchorage",
"zipcode": "99686"
},
"user": {
"email": "90873f61-663e-43d1-8f0c-00415e73f650@example.com",
"name": "Gabi May",
"password": "SecretString",
"password_confirm": "SecretString"
}
}
```
**Note the user email and password from the request to be used in the following steps.**
Click `Execute` and a response with status code 200 should have been returned.
```json
{
"account": {
"id": "baae6e0d-29ae-456f-9648-44c1e90ca8af",
"name": "Company 895ff280-5ed9-4b09-b7bc-86ab0f0951d4",
"address1": "221 Tatitlek Ave",
"address2": "Box #1832",
"city": "Valdez",
"region": "AK",
"country": "USA",
"zipcode": "99686",
"status": "active",
"timezone": "America/Anchorage",
"signup_user_id": {
"String": "bfdc5ca9-872c-4417-8030-e1b4962a107c",
"Valid": true
},
"billing_user_id": {
"String": "bfdc5ca9-872c-4417-8030-e1b4962a107c",
"Valid": true
},
"created_at": "2019-06-25T11:00:53.284Z",
"updated_at": "2019-06-25T11:00:53.284Z"
},
"user": {
"id": "bfdc5ca9-872c-4417-8030-e1b4962a107c",
"name": "Gabi May",
"email": "90873f61-663e-43d1-8f0c-00415e73f650@example.com",
"timezone": "America/Anchorage",
"created_at": "2019-06-25T11:00:53.284Z",
"updated_at": "2019-06-25T11:00:53.284Z"
}
}
```
6. Generate an Auth Token
An auth token is required for all other requests.
Near the top of the Swagger UI locate the button `Authorize` and click it.
Find the section `OAuth2Password (OAuth2, password)`
Enter the user email and password.
Change the type to `basic auth`
Click the button `Authorize` to generate a token that will be used by the Swagger UI for all future requests.
7. Test Auth Token
Now that the Swagger UI is authorized, try running endpoint using the oauth token.
Find the endpoint GET `/accounts/{id}` endpoint in the Swagger UI. This endpoint should return the account by ID.
Click `Try it out` and enter the account ID from generated from signup (step 5).
Click `Execute`. The response should be of an Account.
## API Documentation

105
example-project/cmd/web-api/docs/docs.go
View File

@ -1,6 +1,6 @@
// GENERATED BY THE COMMAND ABOVE; DO NOT EDIT
// This file was generated by swaggo/swag at
// 2019-06-25 02:19:21.144417 -0800 AKDT m=+51.040366621
// 2019-06-25 06:15:54.005963 -0800 AKDT m=+73.603716546
package docs
@ -33,6 +33,11 @@ var doc = `{
"paths": {
"/accounts/{id}": {
"get": {
"security": [
{
"OAuth2Password": []
}
],
"description": "get string by ID",
"consumes": [
"application/json"
@ -44,10 +49,9 @@ var doc = `{
"account"
],
"summary": "Read returns the specified account from the system.",
"operationId": "get-string-by-int",
"parameters": [
{
"type": "integer",
"type": "string",
"description": "Account ID",
"name": "id",
"in": "path",
@ -92,6 +96,62 @@ var doc = `{
}
}
},
"/oauth/token": {
"post": {
"security": [
{
"BasicAuth": []
}
],
"description": "Token generates an oauth2 accessToken using Basic Auth with a user's email and password.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "Token handles a request to authenticate a user.",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"$ref": "#/definitions/user.Token"
},
"headers": {
"Token": {
"type": "string",
"description": "qwerty"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"$ref": "#/definitions/web.Error"
}
},
"403": {
"description": "Forbidden",
"schema": {
"type": "object",
"$ref": "#/definitions/web.Error"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "object",
"$ref": "#/definitions/web.Error"
}
}
}
}
},
"/signup": {
"post": {
"description": "Signup creates a new account and user in the system.",
@ -150,6 +210,11 @@ var doc = `{
},
"/users/{id}": {
"get": {
"security": [
{
"OAuth2Password": []
}
],
"description": "get string by ID",
"consumes": [
"application/json"
@ -161,14 +226,20 @@ var doc = `{
"user"
],
"summary": "Read returns the specified user from the system.",
"operationId": "get-string-by-int",
"parameters": [
{
"type": "integer",
"type": "string",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Authentication header",
"name": "Authorization",
"in": "header",
"required": true
}
],
"responses": {
@ -360,6 +431,20 @@ var doc = `{
}
}
},
"user.Token": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expiry": {
"type": "string"
},
"token_type": {
"type": "string"
}
}
},
"user.User": {
"type": "object",
"required": [
@ -412,10 +497,18 @@ var doc = `{
}
},
"securityDefinitions": {
"BasicAuth": {
"type": "basic"
},
"OAuth2Password": {
"type": "oauth2",
"flow": "password",
"tokenUrl": "/v1/oauth/token"
"tokenUrl": "/v1/oauth/token",
"scopes": {
"admin": " Grants read and write access to administrative information",
"read": " Grants read access",
"write": " Grants write access"
}
}
}
}`

103
example-project/cmd/web-api/docs/swagger.json
View File

@ -20,6 +20,11 @@
"paths": {
"/accounts/{id}": {
"get": {
"security": [
{
"OAuth2Password": []
}
],
"description": "get string by ID",
"consumes": [
"application/json"
@ -31,10 +36,9 @@
"account"
],
"summary": "Read returns the specified account from the system.",
"operationId": "get-string-by-int",
"parameters": [
{
"type": "integer",
"type": "string",
"description": "Account ID",
"name": "id",
"in": "path",
@ -79,6 +83,62 @@
}
}
},
"/oauth/token": {
"post": {
"security": [
{
"BasicAuth": []
}
],
"description": "Token generates an oauth2 accessToken using Basic Auth with a user's email and password.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"user"
],
"summary": "Token handles a request to authenticate a user.",
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object",
"$ref": "#/definitions/user.Token"
},
"headers": {
"Token": {
"type": "string",
"description": "qwerty"
}
}
},
"400": {
"description": "Bad Request",
"schema": {
"type": "object",
"$ref": "#/definitions/web.Error"
}
},
"403": {
"description": "Forbidden",
"schema": {
"type": "object",
"$ref": "#/definitions/web.Error"
}
},
"404": {
"description": "Not Found",
"schema": {
"type": "object",
"$ref": "#/definitions/web.Error"
}
}
}
}
},
"/signup": {
"post": {
"description": "Signup creates a new account and user in the system.",
@ -137,6 +197,11 @@
},
"/users/{id}": {
"get": {
"security": [
{
"OAuth2Password": []
}
],
"description": "get string by ID",
"consumes": [
"application/json"
@ -148,14 +213,20 @@
"user"
],
"summary": "Read returns the specified user from the system.",
"operationId": "get-string-by-int",
"parameters": [
{
"type": "integer",
"type": "string",
"description": "User ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "string",
"description": "Authentication header",
"name": "Authorization",
"in": "header",
"required": true
}
],
"responses": {
@ -347,6 +418,20 @@
}
}
},
"user.Token": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"expiry": {
"type": "string"
},
"token_type": {
"type": "string"
}
}
},
"user.User": {
"type": "object",
"required": [
@ -399,10 +484,18 @@
}
},
"securityDefinitions": {
"BasicAuth": {
"type": "basic"
},
"OAuth2Password": {
"type": "oauth2",
"flow": "password",
"tokenUrl": "/v1/oauth/token"
"tokenUrl": "/v1/oauth/token",
"scopes": {
"admin": " Grants read and write access to administrative information",
"read": " Grants read access",
"write": " Grants write access"
}
}
}
}

68
example-project/cmd/web-api/docs/swagger.yaml
View File

@ -108,6 +108,15 @@ definitions:
$ref: '#/definitions/user.User'
type: object
type: object
user.Token:
properties:
access_token:
type: string
expiry:
type: string
token_type:
type: string
type: object
user.User:
properties:
archived_at:
@ -161,13 +170,12 @@ paths:
consumes:
- application/json
description: get string by ID
operationId: get-string-by-int
parameters:
- description: Account ID
in: path
name: id
required: true
type: integer
type: string
produces:
- application/json
responses:
@ -195,9 +203,49 @@ paths:
schema:
$ref: '#/definitions/web.Error'
type: object
security:
- OAuth2Password: []
summary: Read returns the specified account from the system.
tags:
- account
/oauth/token:
post:
consumes:
- application/json
description: Token generates an oauth2 accessToken using Basic Auth with a user's
email and password.
produces:
- application/json
responses:
"200":
description: OK
headers:
Token:
description: qwerty
type: string
schema:
$ref: '#/definitions/user.Token'
type: object
"400":
description: Bad Request
schema:
$ref: '#/definitions/web.Error'
type: object
"403":
description: Forbidden
schema:
$ref: '#/definitions/web.Error'
type: object
"404":
description: Not Found
schema:
$ref: '#/definitions/web.Error'
type: object
security:
- BasicAuth: []
summary: Token handles a request to authenticate a user.
tags:
- user
/signup:
post:
consumes:
@ -241,13 +289,17 @@ paths:
consumes:
- application/json
description: get string by ID
operationId: get-string-by-int
parameters:
- description: User ID
in: path
name: id
required: true
type: integer
type: string
- description: Authentication header
in: header
name: Authorization
required: true
type: string
produces:
- application/json
responses:
@ -275,12 +327,20 @@ paths:
schema:
$ref: '#/definitions/web.Error'
type: object
security:
- OAuth2Password: []
summary: Read returns the specified user from the system.
tags:
- user
securityDefinitions:
BasicAuth:
type: basic
OAuth2Password:
flow: password
scopes:
admin: ' Grants read and write access to administrative information'
read: ' Grants read access'
write: ' Grants write access'
tokenUrl: /v1/oauth/token
type: oauth2
swagger: "2.0"

4
example-project/cmd/web-api/handlers/account.go
View File

@ -43,10 +43,10 @@ func (a *Account) Find(ctx context.Context, w http.ResponseWriter, r *http.Reque
// @Summary Read returns the specified account from the system.
// @Description get string by ID
// @Tags account
// @ID get-string-by-int
// @Accept json
// @Produce json
// @Param id path int true "Account ID"
// @Security OAuth2Password
// @Param id path string true "Account ID"
// @Success 200 {object} account.Account
// @Header 200 {string} Token "qwerty"
// @Failure 400 {object} web.Error

19
example-project/cmd/web-api/handlers/user.go
View File

@ -48,10 +48,10 @@ func (u *User) Find(ctx context.Context, w http.ResponseWriter, r *http.Request,
// @Summary Read returns the specified user from the system.
// @Description get string by ID
// @Tags user
// @ID get-string-by-int
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Security OAuth2Password
// @Param id path string true "User ID"
// @Success 200 {object} user.User
// @Header 200 {string} Token "qwerty"
// @Failure 400 {object} web.Error
@ -268,8 +268,19 @@ func (u *User) SwitchAccount(ctx context.Context, w http.ResponseWriter, r *http
return web.RespondJson(ctx, w, tkn, http.StatusNoContent)
}
// Token handles a request to authenticate a user. It expects a request using
// Basic Auth with a user's email and password. It responds with a JWT.
// Token godoc
// @Summary Token handles a request to authenticate a user.
// @Description Token generates an oauth2 accessToken using Basic Auth with a user's email and password.
// @Tags user
// @Accept json
// @Produce json
// @Security BasicAuth
// @Success 200 {object} user.Token
// @Header 200 {string} Token "qwerty"
// @Failure 400 {object} web.Error
// @Failure 403 {object} web.Error
// @Failure 404 {object} web.Error
// @Router /oauth/token [post]
func (u *User) Token(ctx context.Context, w http.ResponseWriter, r *http.Request, params map[string]string) error {
v, ok := ctx.Value(web.KeyValues).(*web.Values)
if !ok {

5
example-project/cmd/web-api/main.go
View File

@ -51,8 +51,13 @@ var service = "WEB_API"
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @securityDefinitions.basic BasicAuth
// @securitydefinitions.oauth2.password OAuth2Password
// @tokenUrl /v1/oauth/token
// @scope.read Grants read access
// @scope.write Grants write access
// @scope.admin Grants read and write access to administrative information
func main() {