English | 简体中文

Echoswagger

Swagger UI generator for Echo framework

Feature

• No SwaggerUI HTML/CSS dependency
• Highly integrated with Echo, low intrusive design
• Take advantage of the strong typing language and chain programming to make it easy to use
• Recycle garbage in time, low memory usage

Installation

go get github.com/pangpanglabs/echoswagger

Example

package main

import (
	"net/http"

	"github.com/labstack/echo"
	"github.com/pangpanglabs/echoswagger"
)

func main() {
	// ApiRoot with Echo instance
	r := echoswagger.New(echo.New(), "", "doc/", nil)

	// Routes with parameters & responses
	r.POST("/", createUser).
		AddParamBody(User{}, "body", "User input struct", true).
		AddResponse(http.StatusCreated, "successful", nil, nil)

	// Start server
	r.Echo().Logger.Fatal(r.Echo().Start(":1323"))
}

type User struct {
	Name string
}

// Handler
func createUser(c echo.Context) error {
	return c.JSON(http.StatusCreated, nil)
}

Usage

Create a ApiRoot with New(), which is a wrapper of echo.New()

r := echoswagger.New(echo.New(), "/v1", "doc/", nil)

Note: The parameter basePath is generally used when the access root path is not the root directory of the website after application is deployed. For example, the URL of an API in the program running locally is: http://localhost:1323/users, the actual URL after deployed to server is: https://www.xxx.com/legacy-api/users, then, when running locally, basePath should be /, when running on server, basePath should be /legacy-api.

You can use the result ApiRoot instance to:

• Setup Security definitions, request/response Content-Types, UI options, Scheme, etc.

r.AddSecurityAPIKey("JWT", "JWT Token", echoswagger.SecurityInHeader).
	SetRequestContentType("application/x-www-form-urlencoded", "multipart/form-data").
	SetUI(UISetting{HideTop: true}).
	SetScheme("https", "http")

• Get echo.Echo instance.

r.Echo()

• Registers a new GET, POST, PUT, DELETE, OPTIONS, HEAD or PATCH route in default group, these are wrappers of Echo's create route methods. It returns a new Api instance.

r.GET("/:id", handler)

• And: ↓

Create a ApiGroup with Group(), which is a wrapper of echo.Group()

g := r.Group("Users", "/users")

You can use the result ApiGroup instance to:

• Set description, etc.

g.SetDescription("The desc of group")

• Set security for all routes in this group.

g.SetSecurity("JWT")

• Get echo.Group instance.

g.EchoGroup()

• And: ↓

Registers a new route in ApiGroup

GET, POST, PUT, DELETE, OPTIONS, HEAD or PATCH methods are supported by Echoswagger, these are wrappers of Echo's create route methods.

a := g.GET("/:id", handler)

You can use the result Api instance to:

• Add parameter with these methods:

AddParamPath(p interface{}, name, desc string)

AddParamPathNested(p interface{})

AddParamQuery(p interface{}, name, desc string, required bool)

AddParamQueryNested(p interface{})

AddParamForm(p interface{}, name, desc string, required bool)

AddParamFormNested(p interface{})

AddParamHeader(p interface{}, name, desc string, required bool)

AddParamHeaderNested(p interface{})

AddParamBody(p interface{}, name, desc string, required bool)

AddParamFile(name, desc string, required bool)

The methods which name's suffix are Nested means these methods treat parameter p 's fields as paramters, so it must be a struct type.

e.g.

type SearchInput struct {
	Q         string `query:"q" swagger:"desc("Keywords"),required"`
	SkipCount int    `query:"skipCount"`
}
a.AddParamQueryNested(SearchInput{})

Is equivalent to:

a.AddParamQuery("", "q", "", true).
	AddParamQuery(0, "skipCount", "", false)

• Add responses.

a.AddResponse(http.StatusOK, "response desc", body{}, nil)

• Set Security, request/response Content-Types, summary, description, etc.

a.SetSecurity("JWT").
	SetResponseContentType("application/xml").
	SetSummary("The summary of API").
	SetDescription("The desc of API")

• Get echo.Route instance.

a.Route()

With swagger tag, you can set more info with AddParam... methods.

e.g.

type User struct {
	Age    int       `swagger:"min(0),max(99)"`
	Gender string    `swagger:"enum(male|female|other),required"`
	Money  []float64 `swagger:"default(0),readOnly"`
}
a.AddParamBody(&User{}, "Body", "", true)

The definition is equivalent to:

{
    "definitions": {
        "User": {
            "type": "object",
            "properties": {
                "Age": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0,
                    "maximum": 99
                },
                "Gender": {
                    "type": "string",
                    "enum": [
                        "male",
                        "female",
                        "other"
                    ],
                    "format": "string"
                },
                "Money": {
                    "type": "array",
                    "items": {
                        "type": "number",
                        "default": 0,
                        "format": "double"
                    },
                    "readOnly": true
                }
            },
            "required": [
                "Gender"
            ]
        }
    }
}

Supported swagger tags:

Tag	Type	Description
collect	string	Determines the format of the array if type array is used. Possible values are: csv - comma separated values foo,bar. ssv - space separated values foo bar. tsv - tab separated values foo\tbar. pipes - pipe separated values foo|bar. Default value is csv.
desc	string	Description.
maximum	number	-
minimum	number	-
maxLength	integer	-
minLength	integer	-
allowEmpty	boolean	Sets the ability to pass empty-valued parameters. This is valid only for either query or formData parameters and allows you to send a parameter with a name only or an empty value. Default value is false.
required	boolean	Determines whether this parameter is mandatory. If the parameter is in "path", this property is true without setting. Otherwise, the property MAY be included and its default value is false.
readOnly	boolean	Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false.
enum	[*]	Enumerate value, multiple values should be separated by "|"
default	*	Default value, which type is same as the field's type.

Reference

OpenAPI Specification 2.0

License

MIT