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
- 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
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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.
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 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 {
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
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
example
|
|
|
app/cmd/api
Package main Octane Sample Application
|
Package main Octane Sample Application |
|
app/lib/env
Package env will fill a struct from environment variables.
|
Package env will fill a struct from environment variables. |
|
app/lib/passhash
Package passhash provides password hashing functionality using bcrypt.
|
Package passhash provides password hashing functionality using bcrypt. |
Click to show internal directories.
Click to hide internal directories.