gin-swagger - GitLite

KO | EN

gitlite — search

#javascript #react #llm #golang #machine-learning #rust #linux #docker #macos #java #awesome #cli #awesome-list #security

gin-swagger

(★ 92)

DRY templates for go-swagger

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yaml
- dependabot.yml
- api.go
- - cluster.go
  - cluster_status.go
  - cluster_status_problems_items.go
  - cluster_update.go
  - config_value.go
  - error.go
  - infrastructure_account.go
  - infrastructure_account_update.go
  - list_clusters_o_k_body.go
  - list_infrastructure_accounts_o_k_body.go
  - list_node_pools_o_k_body.go
  - node_pool.go
- - api.go
  - config.go
  - embedded_spec.go
- .gitignore
- main.go
- service.go
- swagger.yaml
- content_types.go
- content_types_test.go
- logger.go
- oauth2.go
- oauth2_test.go
- api.gotmpl
- config.gotmpl
- parameter.gotmpl
- tracing.go
.gitignore
go.mod
go.sum
LICENSE
main.go
Makefile
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# gin-swagger - DRY templates for go-swagger

gin-swagger is a tool assisting in writing golang REST APIs based on a [API
First Principle][api-first]. 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][go-swagger] which is used for the code generation.

## Install

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.
```

## How it works

gin-swagger generates a [gin][gin] based REST API given a swagger spec.

Assuming the following swagger spec:

```yaml
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: string
```

You can generate the REST API using the following command:

```bash
$ gin-swagger -A my-api -f swagger.yaml
```

This 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][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:

```go
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:

```go
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):

```go
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](example).

## Features
* [ ] Validate + bind input to gin ctx.
  * [x] bind body input.
    * [ ] [Nice to have] custom input Models with required fields.
  * [x] bind params input.
  * [x] bind query params input.
  * [ ] consume more than `application/json`
* [ ] Security.
  * [ ] basic
  * [ ] apiKey
  * [ ] OAuth2
    * [x] `password` (Bearer token)
    * [ ] `accessCode`
    * [ ] `application`
    * [ ] `implicit`
  * [ ] Auth chain
  * [x] Custom authorize on individual routes.
* [x] 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)
* [x] OpenTracing support

[api-first]: https://zalando.github.io/restful-api-guidelines/
[gin]: https://github.com/gin-gonic/gin
[go-swagger]: https://github.com/go-swagger/go-swagger