octane

README

Octane

This project contains a library and a template for a Go REST API using Echo and Swagger so you can:

• generate a Swagger spec from annotations in your code - go-swagger
• unmarshal HTML forms and JSON into structs - go-playground/form
• validate struct fields using annotations - go-playground/validator

This project designed to be more of an example of how to create a custom binder for Echo.

Usage

You can add Octane to your Echo application like this:

package main

import (
	"github.com/josephspurrier/octane"
	"github.com/labstack/echo/v4"
)

func main() {
	e := echo.New()

	// Use Octane for binding and validation.
	e.Binder = octane.NewBinder()
}

You can then create endpoints with Swagger annotations that will generate a Swagger spec as well as validate the incoming data using annotations.

package endpoint

import (
	"net/http"

	"github.com/josephspurrier/octane"
	"github.com/josephspurrier/octane/example/app"
	"github.com/josephspurrier/octane/example/app/store"
)

// Login - the annotations below can be used to generate a Swagger spec.
// swagger:route POST /api/v1/login authentication UserLogin
//
// Return a token after verifying the login information.
//
// Responses:
//   200: LoginResponse
//   400: BadRequestResponse
//   500: InternalServerErrorResponse
func Login(c *app.Context) (err error) {
	// swagger:parameters UserLogin
	type Request struct {
		// in: body
		Body struct {
			// Email address.
			// example: jsmith@example.com
			// required: true
			Email string `json:"email" validate:"required,email"` // Binding and validation annotations.
			// Password.
			// example: password
			// required: true
			Password string `json:"password" validate:"required"` // Binding and validation annotations.
		}
	}

	// Request binding and validation.
	req := new(Request)
	if err = c.Bind(req); err != nil {
		return c.BadRequestResponse(err.Error())
	}

    // ... Logic to check password.

	return c.DataResponse(http.StatusOK, data)
}

Documentation

Index

• type BadRequestResponse
• type Binder
  • func NewBinder() *Binder
  • func (b *Binder) Bind(i interface{}, c echo.Context) (err error)
  • func (b *Binder) Unmarshal(iface interface{}, r *http.Request, router IRouter) (err error)
• type CreatedStatusFields
• type IRouter
• type InternalServerErrorResponse
• type NotFoundResponse
• type OKResponse
• type OKStatusFields
• type ResponseJSON
  • func (c *ResponseJSON) BadRequestResponse(message string) error
  • func (c *ResponseJSON) DataResponse(code int, i interface{}) error
  • func (c *ResponseJSON) InternalServerErrorResponse(message string) error
  • func (c *ResponseJSON) MessageResponse(message string, statusCode int) error
  • func (c *ResponseJSON) NotFoundResponse(message string) error
  • func (c *ResponseJSON) OKResponse(message string) error
  • func (c *ResponseJSON) UnauthorizedResponse(message string) error
• type UnauthorizedResponse

Types

type BadRequestResponse

type BadRequestResponse struct {
	// in: body
	Body struct {
		// Message contains a user friendly message.
		// example: The data submitted was invalid.
		// required: true
		Message string `json:"message"`
		// Code contains the HTTP status code.
		// example: 400
		// required: true
		StatusCode int `json:"status_code"`
		// Status contains the string of the HTTP status.
		// example: Bad Request
		// required: true
		StatusMessage string `json:"status_message"`
	}
}

BadRequestResponse is a failure. swagger:response BadRequestResponse

type Binder

type Binder struct {
	// contains filtered or unexported fields
}

Binder contains the request bind an validator objects.

func NewBinder

func NewBinder() *Binder

NewBinder returns a new binder for request bind and validation.

func (*Binder) Bind

func (b *Binder) Bind(i interface{}, c echo.Context) (err error)

Bind will unmarshal and validate a struct from a request.

func (*Binder) Unmarshal

func (b *Binder) Unmarshal(iface interface{}, r *http.Request, router IRouter) (err error)

Unmarshal will perform an unmarshal on an interface using: form or JSON.

type CreatedStatusFields

type CreatedStatusFields struct {
	// Code contains the HTTP status code.
	// example: 201
	// required: true
	StatusCode int `json:"status_code"`
	// Status contains the string of the HTTP status.
	// example: Created
	// required: true
	StatusMessage string `json:"status_message"`
}

CreatedStatusFields should be included in all requests.

type IRouter

type IRouter interface {
	Param(param string) string
}

IRouter extracts a URL parameter value.

type InternalServerErrorResponse

type InternalServerErrorResponse struct {
	// in: body
	Body struct {
		// Message contains a user friendly message.
		// example: An unexpected error occurred in the application.
		// required: true
		Message string `json:"message"`
		// Code contains the HTTP status code.
		// example: 500
		// required: true
		StatusCode int `json:"status_code"`
		// Status contains the string of the HTTP status.
		// example: Internal Server Error
		// required: true
		StatusMessage string `json:"status_message"`
	}
}

InternalServerErrorResponse is a failure. swagger:response InternalServerErrorResponse

type NotFoundResponse

type NotFoundResponse struct {
	// in: body
	Body struct {
		// Message contains a user friendly message.
		// example: The page was not found.
		// required: true
		Message string `json:"message"`
		// Code contains the HTTP status code.
		// example: 404
		// required: true
		StatusCode int `json:"status_code"`
		// Status contains the string of the HTTP status.
		// example: Not Found
		// required: true
		StatusMessage string `json:"status_message"`
	}
}

NotFoundResponse is a failure. swagger:response NotFoundResponse

type OKResponse

type OKResponse struct {
	// in: body
	Body struct {
		// Message contains a user friendly message.
		// example: The operation was successful.
		// required: true
		Message string `json:"message"`
		OKStatusFields
	}
}

OKResponse is a success. swagger:response OKResponse

type OKStatusFields

type OKStatusFields struct {
	// Code contains the HTTP status code.
	// example: 200
	// required: true
	StatusCode int `json:"status_code"`
	// Status contains the string of the HTTP status.
	// example: OK
	// required: true
	StatusMessage string `json:"status_message"`
}

OKStatusFields should be included in all requests.

type ResponseJSON

type ResponseJSON struct {
	echo.Context
}

ResponseJSON -

func (*ResponseJSON) BadRequestResponse

func (c *ResponseJSON) BadRequestResponse(message string) error

BadRequestResponse sends 400.

func (*ResponseJSON) DataResponse

func (c *ResponseJSON) DataResponse(code int, i interface{}) error

DataResponse sends content with a status_code and a status_message to the response writer.

func (*ResponseJSON) InternalServerErrorResponse

func (c *ResponseJSON) InternalServerErrorResponse(message string) error

InternalServerErrorResponse sends 500.

func (*ResponseJSON) MessageResponse

func (c *ResponseJSON) MessageResponse(message string, statusCode int) error

MessageResponse sends a JSON message with a status code.

func (*ResponseJSON) NotFoundResponse

func (c *ResponseJSON) NotFoundResponse(message string) error

NotFoundResponse sends 404.

func (*ResponseJSON) OKResponse

func (c *ResponseJSON) OKResponse(message string) error

OKResponse sends 200.

func (*ResponseJSON) UnauthorizedResponse

func (c *ResponseJSON) UnauthorizedResponse(message string) error

UnauthorizedResponse sends 401.

type UnauthorizedResponse

type UnauthorizedResponse struct {
	// in: body
	Body struct {
		// Message contains a user friendly message.
		// example: You are not authorized to view this page.
		// required: true
		Message string `json:"message"`
		// Code contains the HTTP status code.
		// example: 401
		// required: true
		StatusCode int `json:"status_code"`
		// Status contains the string of the HTTP status.
		// example: Unauthorized
		// required: true
		StatusMessage string `json:"status_message"`
	}
}

UnauthorizedResponse is a failure. swagger:response UnauthorizedResponse