Iris middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at #1231.
- Add comments to your API source code, See Declarative Comments Format.
- Download Swag for Go by using:
$ go install github.com/swaggo/swag/cmd/swag@latest
# if you find swag cli not work, you can try to install swag cli from source
git clone [email protected]:swaggo/swag.git
cd swag
# tag variable should match with github.com/swaggo/swag in go.mod
# here we use v1.8.10
git checkout -b ${tag} tags/${tag}
go install ./cmd/swag- 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 swagger for Iris by using:
$ go get github.com/iris-contrib/swagger/v12@masterAnd import following in your code:
import "github.com/iris-contrib/swagger" // swagger middleware for Iris
import "github.com/iris-contrib/swagger/swaggerFiles" // swagger embed filespackage main
import (
"github.com/kataras/iris/v12"
"github.com/iris-contrib/swagger"
"github.com/iris-contrib/swagger/swaggerFiles"
_ "github.com/your_username/your_project/docs"
// docs folder should be generated by Swag CLI (swag init),
// 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 [email protected]
// @license.name Apache 2.0
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
// @host localhost:8080
// @BasePath /v2
func main() {
app := iris.New()
swaggerUI := swagger.Handler(swaggerFiles.Handler,
swagger.URL("/swagger/doc.json"),
swagger.DeepLinking(true),
swagger.Prefix("/swagger"),
)
// Register on http://localhost:8080/swagger
app.Get("/swagger", swaggerUI)
// And the wildcard one for index.html, *.js, *.css and e.t.c.
app.Get("/swagger/{any:path}", swaggerUI)
app.Listen(":8080")
}-
Run it, and navigate through http://localhost:8080/swagger/index.html, you should see the Swagger 2.0 API documentation page.
-
If you want to disable swagger when some environment variable is set, use
DisablingHandlerinstead ofHandler.
swagger.DisablingHandler(swaggerFiles.Handler, "THE_OS_VARIABLE_NAME_HERE", configurators ...Configurator)- If you want to change swagger-ui theme, you can add
swagger.SetTheme(swagger.Monokai)when initswaggerUI
swaggerUI := swagger.Handler(swaggerFiles.Handler,
swagger.URL("/swagger/doc.json"),
swagger.DeepLinking(true),
swagger.Prefix("/swagger"),
// ref: https://github.com/ostranme/swagger-ui-themes
// current we support 7 themes
// theme is a optional config, if you not set, it will use default theme
swagger.SetTheme(swagger.Monokai),
)
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent