swagger

README

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

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/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 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()

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

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

Documentation

Index

• func Disable(h *webdav.Handler, configurators ...Configurator) iris.Handler
• func DisablingHandler(h *webdav.Handler, envName string, configurators ...Configurator) iris.Handler
• func Handler(h *webdav.Handler, configurators ...Configurator) iris.Handler
• type Config
  • func (c Config) Configure(config *Config)
• type Configurator
• type ConfiguratorFunc
  • func DeepLinking(deepLinking bool) ConfiguratorFunc
  • func DocExpansion(docExpansion string) ConfiguratorFunc
  • func DomID(domID string) ConfiguratorFunc
  • func Prefix(prefix string) ConfiguratorFunc
  • func URL(url string) ConfiguratorFunc
  • func (fn ConfiguratorFunc) Configure(config *Config)

Functions

func Disable

func Disable(h *webdav.Handler, configurators ...Configurator) iris.Handler

Disable turns handler off if called.

func DisablingHandler

func DisablingHandler(h *webdav.Handler, envName string, configurators ...Configurator) iris.Handler

DisablingHandler turns handler off if specified environment variable passed.

func Handler

func Handler(h *webdav.Handler, configurators ...Configurator) iris.Handler

Handler wraps the webdav http handler into an Iris Handler one.

Usage:

swaggerUI := swagger.Handler(swaggerFiles.Handler,
 swagger.URL("http://localhost:8080/swagger/doc.json"), // The url pointing to API definition))
 swagger.DeepLinking(true),
 swagger.Prefix("/swagger"),
)
app.Get("/swagger", swaggerUI)
app.Get("/swagger/{any:path}", swaggerUI)

OR

swaggerUI := swagger.Handler(swaggerFiles.Handler, swagger.Config{
 URL: ...,
 Prefix: ...,
 DeepLinking: ...,
 DocExpansion: ...,
 DomID: ...,
}

Types

type Config

type Config struct {
	// The URL pointing to API definition (normally swagger.json or swagger.yaml).
	// Default is `doc.json`.
	URL string
	// The prefix url which this swagger ui is registered on.
	// Defaults to "/swagger". It can be a "." too.
	Prefix       string
	DeepLinking  bool
	DocExpansion string
	DomID        string
}

Config stores swagger configuration variables.

func (Config) Configure

func (c Config) Configure(config *Config)

Configure completes the Configurator interface. It allows to pass a Config as it is and override any option.

type Configurator

type Configurator interface {
	Configure(*Config)
}

Configurator represents a configuration setter.

type ConfiguratorFunc

type ConfiguratorFunc func(*Config)

ConfiguratorFunc implements the Configuration as a function type.

func DeepLinking

func DeepLinking(deepLinking bool) ConfiguratorFunc

DeepLinking set the swagger deeplinking configuration.

func DocExpansion

func DocExpansion(docExpansion string) ConfiguratorFunc

DocExpansion list, full, none.

func DomID

func DomID(domID string) ConfiguratorFunc

DomID #swagger-ui.

func Prefix

func Prefix(prefix string) ConfiguratorFunc

Prefix presents the URL prefix of this swagger UI (normally "/swagger" or ".").

func URL

func URL(url string) ConfiguratorFunc

URL presents the URL pointing to API definition (normally swagger.json or swagger.yaml).

func (ConfiguratorFunc) Configure

func (fn ConfiguratorFunc) Configure(config *Config)

Configure calls itself and modifies the default config.