gin-swagger is a tool assisting in writing golang REST APIs based on a API
First Principle. Given a swagger spec of your REST API,
gin-swagger can generate all the boring boilerplate stuff for you, so you
only have to implement the core business logic of the API.
It is based on go-swagger which is used for the code generation.
You can simply run go get to install gin-swagger.
$ go get github.com/mikkeloscar/gin-swagger
$ gin-swagger --help
usage: gin-swagger --application=APPLICATION [<flags>]
Flags:
--help Show context-sensitive help (also try --help-long and --help-man).
-A, --application=APPLICATION Name of the application (passed directly to swagger).
-f, --spec="./swagger.json" the spec file to use.
gin-swagger generates a gin based REST API given a swagger spec.
Assuming the following swagger spec:
swagger: '2.0'
info:
version: "0.0.1"
title: My API
schemes:
- "https"
basePath: /
produces:
- application/json
consumes:
- application/json
paths:
'/persons/{name}':
get:
summary: get Person
tags:
- Person
operationId: getPerson
responses:
200:
description: Person by name.
schema:
'$ref': '#/definitions/Person'
parameters:
name:
name: name
in: path
type: string
required: true
pattern: "^[a-z][a-z0-9]$"
definitions:
Person:
type: object
properties:
name:
type: stringYou can generate the REST API using the following command:
$ gin-swagger -A my-api -f swagger.yamlThis will generate two folders models/ and restapi/. models/ contains
model structs based on the definitions defined in your swagger file,
including model validation, this is generated by go-swagger.
restapi/ will contain everything generated by gin-swagger and can be
overwritten when updating and regenerating your swagger spec. restapi/api.go
will contain a generated Service interface which is all you have to implement
in order to add logic to your REST api.
Given the above swagger spec, the Service interface will look like this:
type Service interface {
Healthy() bool
GetPerson(ctx *gin.Context, params *persons.GetPersonParams) *api.Response
}The Healthy() bool method should return true if the service is considered
healthy. The return value is used by the default health endpoint /healthz
provided by gin-swagger.
The GetPerson() method should implement the business logic of the
/persons/{name} path of your REST API.
A simple service implementation looks like this:
type mySvc struct {
health bool
}
func (m *mySvc) GetPerson(ctx *gin.Context, params *persons.GetPersonParams) *api.Response {
return &api.Response{
Code: http.StatusOK,
Body: &models.Person{Name: params.Name},
}
}
func (m *mySvc) Healthy() bool {
return m.health
}With the service implemented the only thing left to do is plug it into
gin-swagger and run it from your main.go (or wherever you like):
package main
import ...
var apiConfig restapi.Config
func main() {
err := apiConfig.Parse()
if err != nil {
log.Fatal(err)
}
svc := &mySvc{health: true}
api := restapi.NewServer(svc, &apiConfig)
err = api.RunWithSigHandler()
if err != nil {
log.Fatal(err)
}
}restapi.Config is a default config object defined by gin-swagger it lets
you configure default options through commandline flags when starting the
server. For instance you can tell the server to serve HTTP only with the
--insecure-http flag (default is to serve HTTPS).
For a full example see the example folder.
- Validate + bind input to gin ctx.
- bind body input.
- [Nice to have] custom input Models with required fields.
- bind params input.
- bind query params input.
- consume more than
application/json
- bind body input.
- Security.
- basic
- apiKey
- OAuth2
-
password(Bearer token) -
accessCode -
application -
implicit
-
- Auth chain
- Custom authorize on individual routes.
- Set custom middleware on each router Pre/post 'main' handler.
- Use case pre: custom authorization pre handler.
- Use case post: audit report events post handler.
- Ginize generated code.
- Set and get user info (uid, realm) from gin context.
- Response helper functions
- Default metrics (prometheus)
- OpenTracing support
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent