Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fourcels/rest
RESTful Web Services base on Echo
https://github.com/fourcels/rest
echo go jsonschema openapi3 restful
Last synced: about 1 month ago
JSON representation
RESTful Web Services base on Echo
- Host: GitHub
- URL: https://github.com/fourcels/rest
- Owner: fourcels
- License: mit
- Created: 2023-04-24T08:42:46.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-07-12T06:35:07.000Z (4 months ago)
- Last Synced: 2024-10-01T05:01:17.299Z (about 2 months ago)
- Topics: echo, go, jsonschema, openapi3, restful
- Language: Go
- Homepage:
- Size: 46.9 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# REST with Clean Architecture for Go
[](https://pkg.go.dev/github.com/fourcels/rest)
Inspired by [swaggest/rest](https://github.com/swaggest/rest)
## Features
- Built with [echo](https://github.com/labstack/echo).
- Automatic OpenAPI 3 documentation with
[openapi-go](https://github.com/swaggest/openapi-go).
- Automatic request JSON schema validation with
[jsonschema-go](https://github.com/swaggest/jsonschema-go),
[jsonschema](https://github.com/santhosh-tekuri/jsonschema).
- Embedded [Swagger UI](https://swagger.io/tools/swagger-ui/).
## Usage
### Request
Go struct with field tags defines input.
```go
// Declare input port type.
type helloInput struct {
Locale string `query:"locale" default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$" enum:"zh-CN,en-US"`
Name string `path:"name" minLength:"3"` // Field tags define parameter location and JSON schema constraints.
_ struct{} `title:"My Struct" description:"Holds my data."`
}
```
Input data can be located in:
- `path` parameter in request URI, e.g. `/users/:name`,
- `query` parameter in request URI, e.g. `/users?locale=en-US`,
- `form` parameter in request body with `application/x-www-form-urlencoded`
content,
- `formData` parameter in request body with `multipart/form-data` content,
- `json` parameter in request body with `application/json` content,
- `cookie` parameter in request cookie,
- `header` parameter in request header.
Field tags
- number `maximum`, `exclusiveMaximum`, `minimum`, `exclusiveMinimum`,
`multipleOf`
- string `minLength`, `maxLength`, `pattern`, `format`
- array `minItems`, `maxItems`, `uniqueItems`
- all `title`, `description`, `default`, `const`, `enum`
Additional field tags describe JSON schema constraints, please check
[documentation](https://github.com/swaggest/jsonschema-go#field-tags).
## Response
```go
// Declare output port type.
type helloOutput struct {
Now time.Time `header:"X-Now" json:"-"`
Message string `json:"message"`
Sess string `cookie:"sess,httponly,secure,max-age=86400,samesite=lax"`
}
```
Output data can be located in:
- `json` for response body with `application/json` content,
- `header` for values in response header,
- `cookie` for cookie values, cookie fields can have configuration in field tag
(same as in actual cookie, but with comma separation).
## Example
[Advance Example](/examples/advance/main.go)
```go
package main
import (
"fmt"
"log"
"time"
"github.com/fourcels/rest"
"github.com/labstack/echo/v4"
)
func main() {
s := rest.NewService()
s.OpenAPI.Info.WithTitle("Basic Example")
s.GET("/hello/{name}", hello())
// Swagger UI endpoint at /docs.
s.Docs("/docs")
// Start server.
log.Println("http://localhost:1323/docs")
s.Start(":1323")
}
func hello() rest.Interactor {
// Declare input port type.
type input struct {
Name string `path:"name" minLength:"3"` // Field tags define parameter
Locale string `query:"locale" default:"en-US" pattern:"^[a-z]{2}-[A-Z]{2}$" enum:"zh-CN,en-US"`
_ struct{} `title:"My Struct" description:"Holds my data."`
}
// Declare output port type.
type output struct {
Now time.Time `header:"X-Now" json:"-"`
Message string `json:"message"`
}
messages := map[string]string{
"en-US": "Hello, %s!",
"zh-CN": "你好, %s!",
}
return rest.NewHandler(func(c echo.Context, in input, out *output) error {
msg := messages[in.Locale]
out.Now = time.Now()
out.Message = fmt.Sprintf(msg, in.Name)
return nil
})
}
```