README.md

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

1. Add comments to your API source code, See Declarative Comments Format.
2. 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 git@github.com: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

3. Run the Swag in your Go project root folder which contains main.go file, Swag will parse comments and generate required files(docs folder and docs/doc.go).

$ swag init

4. 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" // swagger middleware for Iris 
import "github.com/iris-contrib/swagger/swaggerFiles" // swagger embed files

Example Code:

package 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 support@swagger.io

// @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")
}

5. Run it, and navigate through http://localhost:8080/swagger/index.html, you should see the Swagger 2.0 API documentation page.

6. If you want to disable swagger when some environment variable is set, use DisablingHandler instead of Handler.

swagger.DisablingHandler(swaggerFiles.Handler, "THE_OS_VARIABLE_NAME_HERE", configurators ...Configurator)

7. If you want to change swagger-ui theme, you can add swagger.SetTheme(swagger.Monokai) when init swaggerUI

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),
)