If you use Fiber, you can try my another similar project Fibers.
SwaGin is a web framework based on Gin and Swagger, which wraps Gin and provides built-in swagger api docs and
request model validation.
Previous I have used FastAPI, which gives me a great experience in api docs generation, because nobody like writing api docs.
Now I use Gin but I can't found anything like that, I found swag but which write
docs with comment is so stupid. So there is SwaGin.
go get -u github.com/long2ice/swaginYou can see online demo at https://swagin.long2ice.io/docs or https://swagin.long2ice.io/redoc.
And you can reference all usage in examples.
Firstly, build a swagger object with basic information.
package examples
import (
"github.com/getkin/kin-openapi/openapi3"
"github.com/long2ice/swagin/swagger"
)
func NewSwagger() *swagger.Swagger {
return swagger.New("SwaGin", "Swagger + Gin = SwaGin", "0.1.0",
swagger.License(&openapi3.License{
Name: "Apache License 2.0",
URL: "https://github.com/long2ice/swagin/blob/dev/LICENSE",
}),
swagger.Contact(&openapi3.Contact{
Name: "long2ice",
URL: "https://github.com/long2ice",
Email: "[email protected]",
}),
swagger.TermsOfService("https://github.com/long2ice"),
)
}Then make api struct which implement router.IAPI.
package examples
type TestQuery struct {
Name string `query:"name" validate:"required" json:"name" description:"name of model" default:"test"`
}
func (t *TestQuery) Handler(c *gin.Context) {
c.JSON(http.StatusOK, t)
}Note that the attributes in TestQuery? SwaGin will validate request and inject it automatically, then you can use it
in handler easily.
Then write router with some docs configuration and api.
package examples
var query = router.New(
&TestQuery{},
router.Summary("Test Query"),
router.Description("Test Query Model"),
router.Tags("Test"),
)If you want to project your api with a security policy, you can use security, also they will be shown in swagger docs.
Current there is five kinds of security policies.
BasicBearerApiKeyOpenIDOAuth2
package main
var query = router.New(
&TestQuery{},
router.Summary("Test query"),
router.Description("Test query model"),
router.Security(&security.Basic{}),
)Then you can get the authentication string by context.MustGet(security.Credentials) depending on your auth type.
package main
func (t *TestQuery) Handler(c *gin.Context) {
user := c.MustGet(security.Credentials).(*security.User)
fmt.Println(user)
c.JSON(http.StatusOK, t)
}Then you can mount router in your application or group.
package main
func main() {
app := swagin.New(NewSwagger())
queryGroup := app.Group("/query", swagin.Tags("Query"))
queryGroup.GET("", query)
queryGroup.GET("/:id", queryPath)
queryGroup.DELETE("", query)
app.GET("/noModel", noModel)
}Finally, start the application with routes defined.
package main
import (
"github.com/gin-contrib/cors"
"github.com/long2ice/swagin"
)
func main() {
app := swagin.New(NewSwagger())
app.Use(cors.New(cors.Config{
AllowOrigins: []string{"*"},
AllowMethods: []string{"*"},
AllowHeaders: []string{"*"},
AllowCredentials: true,
}))
queryGroup := app.Group("/query", swagin.Tags("Query"))
queryGroup.GET("", query)
queryGroup.GET("/:id", queryPath)
queryGroup.DELETE("", query)
formGroup := app.Group("/form", swagin.Tags("Form"))
formGroup.POST("/encoded", formEncode)
formGroup.PUT("", body)
app.GET("/noModel", noModel)
app.POST("/body", body)
if err := app.Run(); err != nil {
panic(err)
}
}That's all! Now you can visit http://127.0.0.1:8080/docs or http://127.0.0.1:8080/redoc to see the api docs. Have fun!
In some cases you may want to disable docs such as in production, just put nil to swagin.New.
app = swagin.New(nil)If you want to use sub application, you can mount another SwaGin instance to main application, and their swagger docs
is also separate.
package main
func main() {
app := swagin.New(NewSwagger())
subApp := swagin.New(NewSwagger())
subApp.GET("/noModel", noModel)
app.Mount("/sub", subApp)
}- kin-openapi, OpenAPI 3.0 implementation for Go (parsing, converting, validation, and more).
- Gin, an HTTP web framework written in Go (Golang).
This project is licensed under the Apache-2.0 License.