swagger

package module
v0.0.0-...-88539f4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2022 License: MIT Imports: 6 Imported by: 0

README

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

Constants

This section is empty.

Variables

This section is empty.

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.

Directories

Path Synopsis
_examples
basic/docs
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag
Package docs GENERATED BY THE COMMAND ABOVE; DO NOT EDIT This file was generated by swaggo/swag

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL