English | [简体中文](./README_zh-CN.md) # Echoswagger Swagger UI generator for Echo framework [![Go Report Card](https://goreportcard.com/badge/github.com/pangpanglabs/echoswagger)](https://goreportcard.com/report/github.com/pangpanglabs/echoswagger) [![Build Status](https://travis-ci.org/pangpanglabs/echoswagger.svg?branch=master)](https://travis-ci.org/pangpanglabs/echoswagger) [![codecov](https://codecov.io/gh/pangpanglabs/echoswagger/branch/master/graph/badge.svg)](https://codecov.io/gh/pangpanglabs/echoswagger) ## 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 ```go package main import ( "net/http" "github.com/labstack/echo" "github.com/pangpanglabs/echoswagger" ) func main() { // ApiRoot with Echo instance r := echoswagger.New(echo.New(), "/v1", "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) ``` You can use the result `ApiRoot` instance to: - Setup Security definitions, request/response Content-Types, UI options, etc. ``` r.AddSecurityAPIKey("JWT", "JWT Token", echoswagger.SecurityInHeader). SetRequestContentType("application/x-www-form-urlencoded", "multipart/form-data"). SetUI(UISetting{HideTop: true}) ``` - 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: 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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) ## License [MIT](https://github.com/pangpanglabs/echoswagger/blob/master/LICENSE)