https://github.com/swaggo/echo-swagger
echo middleware to automatically generate RESTful API documentation with Swagger 2.0.
https://github.com/swaggo/echo-swagger
echo echo-framework golang middleware swagger2
Last synced: about 14 hours ago
JSON representation
echo middleware to automatically generate RESTful API documentation with Swagger 2.0.
- Host: GitHub
- URL: https://github.com/swaggo/echo-swagger
- Owner: swaggo
- License: mit
- Created: 2017-06-22T00:46:11.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T20:59:45.000Z (over 1 year ago)
- Last Synced: 2025-04-27T04:56:56.473Z (11 months ago)
- Topics: echo, echo-framework, golang, middleware, swagger2
- Language: Go
- Homepage:
- Size: 83 KB
- Stars: 852
- Watchers: 12
- Forks: 132
- Open Issues: 32
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - echo-swagger - echo middleware to automatically generate RESTful API documentation with Swagger 2.0. (Middlewares & framework add-ons)
README
# echo-swagger
echo middleware to automatically generate RESTful API documentation with Swagger 2.0.
[](https://github.com/features/actions)
[](https://codecov.io/gh/swaggo/echo-swagger)
[](https://goreportcard.com/report/github.com/swaggo/echo-swagger)
[](https://github.com/swaggo/echo-swagger/releases)
## Usage
### Start using it
1. Add comments to your API source code, [See Declarative Comments Format](https://github.com/swaggo/swag#declarative-comments-format).
2. Download [Swag](https://github.com/swaggo/swag) for Go by using:
```sh
$ go get -d github.com/swaggo/swag/cmd/swag
# 1.21 or newer
$ go install github.com/swaggo/swag/cmd/swag@latest
```
3. Run the [Swag](https://github.com/swaggo/swag) in your Go project root folder which contains `main.go` file, [Swag](https://github.com/swaggo/swag) will parse comments and generate required files(`docs` folder and `docs/doc.go`).
```sh_ "github.com/swaggo/echo-swagger/v2/example/docs"
$ swag init
```
4. Download [echo-swagger](https://github.com/swaggo/echo-swagger) by using:
```sh
$ go get -u github.com/swaggo/echo-swagger
```
And import following in your code:
```go
import "github.com/swaggo/echo-swagger" // echo-swagger middleware
```
### Canonical example:
## OpenAPI Specification (OAS) 2.0
```go
package main
import (
"github.com/labstack/echo/v5"
"github.com/swaggo/echo-swagger/v2"
_ "github.com/swaggo/echo-swagger/v2/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
```go
package main
import (
"github.com/labstack/echo/v5"
"github.com/swaggo/echo-swagger/v2"
_ "github.com/swaggo/echo-swagger/v2/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"))
}
```
5. 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
},
}))
```