swagger
swagger copied to clipboard
Iris middleware to automatically generate RESTful API documentation with Swagger 2.0
Swagger for the Iris web framework
Iris middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at #1231.
Usage
Start using it
- 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
- Run the Swag in your Go project root folder which contains
main.go
file, Swag will parse comments and generate required files(docs
folder anddocs/doc.go
).
$ swag init
- Download swagger for Iris by using:
$ go get github.com/iris-contrib/swagger/v12@master
And import following in your code:
import "github.com/iris-contrib/swagger/v12" // swagger middleware for Iris
import "github.com/iris-contrib/swagger/v12/swaggerFiles" // swagger embed files
Example Code:
package main
import (
"github.com/kataras/iris/v12"
"github.com/iris-contrib/swagger/v12"
"github.com/iris-contrib/swagger/v12/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()
config := swagger.Config{
// The url pointing to API definition.
URL: "http://localhost:8080/swagger/doc.json",
DeepLinking: true,
DocExpansion: "list",
DomID: "#swagger-ui",
// The UI prefix URL (see route).
Prefix: "/swagger",
}
swaggerUI := swagger.Handler(swaggerFiles.Handler, config)
// 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
DisablingHandler
instead ofHandler
.
swagger.DisablingHandler(swaggerFiles.Handler, "THE_OS_VARIABLE_NAME_HERE", config)