Generates code from a Swagger spec for GIN Framework. Currently, only server code generation is supported.
Disclaimer: This project uses code generation framework on https://github.com/go-swagger/go-swagger. Also, templates from https://github.com/mikkeloscar/gin-swagger have been used as a base for the templates in this project.
go get github.com/emreisikligil/gin-swagger
or install from the source
go install .
Usage:
gin-swagger server [flags]
Flags:
-p, --api-package string api-package name (default "operations")
-c, --client-package string client-package name (default "client")
--exclude-spec Excludes spec if set
-h, --help help for server
--include-handler Generates operation handlers if set (default true)
--include-main Generates main function if set
--include-models Generates models if set (default true)
--include-support Generates support docs if set (default true)
--include-validation Generates validators if set (default true)
-m, --model-package string model-package name (default "models")
-n, --name string name (default "name")
-s, --server-package string server-package name (default "restapi")
--skip-operations Skips operations if set
--spec string spec name (default "api/swagger.yml")
--target string target name (default "./")
-t, --toggle Help message for toggle
A sample server is provided under example folder. It has been generated using
cd example
gin-swagger server --name example --spec spec.yml
API key authorization and oauth2 application flow are supported currently. Check Swagger for more details about the authentications methods.
Consider the following security definitions.
securityDefinitions:
oauth2:
type: oauth2
authorizationUrl: http://petstore.swagger.io/oauth/dialog
flow: application
scopes:
read: read your pets
write: modify pets in your account
apiKey:
type: apiKey
name: X-API-Key
in: header
scopes:
read: read your pets
write: modify pets in your account
It adds the following 2 functions to the service interface
APIKeyAuthenticate(*gin.Context, string, []string) (interface{}, error, int)
Oauth2Authenticate(*gin.Context, string, []string) (interface{}, error, int)
These functions are supposed to handle authorization. Both functions return the same triplet which is (principal, error, status_code). status_code is used as http response code when error is not nil. Otherwise, it is not used. principal is the entity who makes the request. If the authorization succeeds these functions should return an object identifying the caller. Object returned by one of these functions is added to the context with "Principal" key.
The first and the third arguments of this functions are the gin context and the required scopes. The second argument is the API key for API key authorization and Authorization header for oauth2 authorization.
Assume an operation is tagged with
...
security:
- apiKey: [read]
- oauth2: [read]
...
Authenticator functions will be called in the given order. If any of the functions returns success the following authenticators are skipped and the request is passed to the handler. If none of the authenticators returns success status_code and error returned by the last authenticator will be returned as HTTP response.
APIKeyAuthenticate(ctx, "<api_key>", []string{"read"})
Oauth2Authenticate(ctx, "<authorization_token>", []string{"read"})
API operations are added to the service interface along with the authenticators. All you have to do is to implement functions in this interface.
type ExampleService interface {
// Authenticator Handlers
APIKeyAuthenticate(*gin.Context, string, []string) (interface{}, error, int)
Oauth2Authenticate(*gin.Context, string, []string) (interface{}, error, int)
// API Operation Handlers
AddPet(ctx *gin.Context, params *pet.AddPetParams) api.APIResponse
GetPetByID(ctx *gin.Context, params *pet.GetPetByIDParams) api.APIResponse
Generated code will have the following CORS configuration. Currently, it is not possible to modify this configuration through CLI. Templates may be edited in order to modify this behaviour.
import "github.com/gin-contrib/cors"
...
config := cors.DefaultConfig()
config.AllowHeaders = append(config.AllowHeaders, "Authorization")
config.AllowAllOrigins = true
server.Router.Use(cors.New(config))
Templates can be edited using the following steps.
-
Edit templates
-
Use
go-bindata
to generate template binaries again.go get -u github.com/jteeuwen/go-bindata go-bindata -o cmd/bindata.go -pkg cmd templates go install .