crud
A Swagger/OpenAPI builder and validation library for building HTTP/REST APIs.
Heavily inspired by hapi and the hapi-swagger projects.
No additional dependencies besides the router you choose.
Status
This project is not stable yet, API is still changing occasionally and there are missing features.
That being said, it's already pretty useful! If you are not risk averse then use it and pitch in.
Why
Swagger is great, but up until now your options to use swagger are:
- Write it by hand and then make your server match your spec.
- Write it by hand and generate your server.
- Generate it from comments in your code.
None of these options seems like a great idea.
This project takes another approach: make a specification in Go code using nice builders where possible. The swagger is generated from this spec and validation is done before your handler gets called.
This reduces boilerplate that you have to write and gives you nice documentation too!
Examples
Getting started
Check the example directory under the adapters for a simple example.
Start by getting the package go get github.com/jakecoffman/crud
Then in your main.go:
- Create a router with
NewRouter, use an adapter from theadapterssub-package or write you own. - Add routes with
Add. - Then call
Serve.
Routes are specifications that look like this:
crud.Spec{
Method: "PATCH",
Path: "/widgets/{id}",
PreHandlers: Auth,
Handler: CreateHandler,
Description: "Adds a widget",
Tags: []string{"Widgets"},
Validate: crud.Validate{
Path: crud.Object(map[string]crud.Field{
"id": crud.Number().Required().Description("ID of the widget"),
}),
Body: crud.Object(map[string]crud.Field{
"owner": crud.String().Required().Example("Bob").Description("Widget owner's name"),
"quantity": crud.Integer().Min(1).Default(1).Description("The amount requested")
}),
},
}
This will add a route /widgets/:id that responds to the PATCH method. It generates swagger and serves it at the root of the web application. It validates that the ID in the path is a number, so you don't have to. It also validates that the body is an object and has an "owner" property that is a string, again so you won't have to.
It mounts the swagger-ui at / and loads up the generated swagger.json:
The PreHandlers run before validation, and the Handler runs after validation is successful.
79 Dec 16, 2022
15 Nov 9, 2022
12.2k Jan 1, 2023
824 Dec 28, 2022
883 Dec 25, 2022
32 Dec 6, 2022
1.2k Dec 29, 2022
1.3k Jan 9, 2023
0 Jul 21, 2022
1 Sep 4, 2022
0 Jan 14, 2022
2 Jan 18, 2022
5.6k Jan 6, 2023
96 Dec 17, 2022
79 Nov 29, 2022
0 Oct 20, 2021
57 Dec 30, 2022
7 Nov 5, 2022
3k Jan 7, 2023