Skip to content

Iris middleware to automatically generate RESTful API documentation with Swagger 2.0

License

Notifications You must be signed in to change notification settings

iris-contrib/swagger

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

24 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Swagger for the Iris web framework

Iris middleware to automatically generate RESTful API documentation with Swagger 2.0 as requested at #1231.

build status Go Report Card

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 [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
  1. 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
  1. 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 [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")
}
  1. Run it, and navigate through http://localhost:8080/swagger/index.html, you should see the Swagger 2.0 API documentation page.

  2. 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)
  1. 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),
)