README
¶
echo-swagger
echo middleware to automatically generate RESTful API documentation with Swagger 2.0.
[!IMPORTANT] This repository is just an updated fork of swaggo/echo-swagger. The main reason for this fork is to keep the module up-to-date with the latest Echo and Swag versions, as the original repository takes some time to approve changes and release updates.
Usage
Start using it
- Add comments to your API source code, See Declarative Comments Format.
- Download Swag for Go by using:
$ go get -d github.com/swaggo/swag/cmd/swag
# 1.21 or newer
$ go install github.com/swaggo/swag/cmd/swag@latest
- Run the Swag in your Go project root folder which contains
main.gofile, Swag will parse comments and generate required files(docsfolder anddocs/doc.go).
$ swag init
- Download echo-swagger by using:
$ go get -u github.com/BrunoKrugel/echo-swagger
And import following in your code:
import "github.com/BrunoKrugel/echo-swagger" // echo-swagger middleware
Canonical example:
OpenAPI Specification (OAS) 2.0
package main
import (
"github.com/labstack/echo/v4"
"github.com/BrunoKrugel/echo-swagger"
_ "github.com/BrunoKrugel/echo-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.
)
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host petstore.swagger.io
// @BasePath /v2
func main() {
e := echo.New()
e.GET("/swagger/*", echoSwagger.WrapHandler)
e.Logger.Fatal(e.Start(":1323"))
}
OpenAPI Specification (OAS) 3.0
package main
import (
"github.com/labstack/echo/v4"
"github.com/BrunoKrugel/echo-swagger"
_ "github.com/BrunoKrugel/echo-swagger/example/docs" // docs is generated by Swag CLI, you have to import it.
)
// @title Swagger Example API
// @version 1.0
// @description This is a sample server Petstore server.
// @termsOfService http://swagger.io/terms/
// @contact.name API Support
// @contact.url http://www.swagger.io/support
// @contact.email support@swagger.io
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host petstore.swagger.io
// @BasePath /v2
func main() {
e := echo.New()
e.GET("/swagger/*", echoSwagger.WrapHandlerV3)
e.Logger.Fatal(e.Start(":1323"))
}
- Run it, and browser to http://localhost:1323/swagger/index.html, you can see Swagger 2.0 Api documents.
Note: If you are using Gzip middleware you should add the swagger endpoint to skipper
Example
e.Use(middleware.GzipWithConfig(middleware.GzipConfig{
Skipper: func(c echo.Context) bool {
if strings.Contains(c.Request().URL.Path, "swagger") {
return true
}
return false
},
}))
Documentation
¶
Index ¶
- Variables
- func DeepLinking(deepLinking bool) func(*Config)
- func DefaultModelsExpandDepth(depth int) func(*Config)
- func DocExpansion(docExpansion string) func(*Config)
- func DomID(domID string) func(*Config)
- func EchoWrapHandler(options ...func(*Config)) echo.HandlerFunc
- func EchoWrapHandlerV3(options ...func(*Config)) echo.HandlerFunc
- func InstanceName(instanceName string) func(*Config)
- func OAuth(config *OAuthConfig) func(*Config)
- func PersistAuthorization(persistAuthorization bool) func(*Config)
- func SyntaxHighlight(syntaxHighlight bool) func(*Config)
- func TryItOutEnabled(enable bool) func(*Config)
- func URL(url string) func(*Config)
- type Config
- type OAuthConfig
Constants ¶
This section is empty.
Variables ¶
var ( WrapHandler = EchoWrapHandler() WrapHandlerV3 = EchoWrapHandlerV3() )
WrapHandler wraps swaggerFiles.Handler and returns echo.HandlerFunc
Functions ¶
func DefaultModelsExpandDepth ¶
DefaultModelsExpandDepth expansion depth for models (set -1 to completely hide the models). Defaults to 1
func DocExpansion ¶
DocExpansion list, full, none.
func EchoWrapHandler ¶
func EchoWrapHandler(options ...func(*Config)) echo.HandlerFunc
EchoWrapHandler wraps `http.Handler` into `echo.HandlerFunc`.
func EchoWrapHandlerV3 ¶
func EchoWrapHandlerV3(options ...func(*Config)) echo.HandlerFunc
EchoWrapHandler wraps `http.Handler` into `echo.HandlerFunc`.
func InstanceName ¶
InstanceName specified swag instance name.
func OAuth ¶
func OAuth(config *OAuthConfig) func(*Config)
func PersistAuthorization ¶
PersistAuthorization Persist authorization information over browser close/refresh. Defaults to false.
func SyntaxHighlight ¶
SyntaxHighlight true, false.
func TryItOutEnabled ¶
TryItOutEnabled controls whether the "Try it out" section should be enabled by default. Defaults to true
Types ¶
type Config ¶
type Config struct {
OAuth *OAuthConfig // The information for OAuth2 integration, if any.
DocExpansion string
DomID string
InstanceName string
URLs []string // The url pointing to API definition (normally swagger.json or swagger.yaml). Default is `mockedSwag.json`.
DeepLinking bool
PersistAuthorization bool
SyntaxHighlight bool
TryItOutEnabled bool
DefaultModelsExpandDepth int
}
Config stores echoSwagger configuration variables.
type OAuthConfig ¶
type OAuthConfig struct {
// The ID of the client sent to the OAuth2 IAM provider.
ClientId string
// The OAuth2 realm that the client should operate in. If not applicable, use empty string.
Realm string
// The name to display for the application in the authentication popup.
AppName string
}
OAuthConfig stores configuration for Swagger UI OAuth2 integration. See https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/ for further details.
Source Files