worldline-go / swagger

swaggo extension library

swagger

This is for swaggo extension library to set extra variables without touching the generated file.

go get github.com/worldline-go/swagger

Usage

Create a file in the /docs/ folder, add to that folder to not include again generated file of swaggo.

Example /docs/info.go:

package docs

import (
	"github.com/worldline-go/auth"
	"github.com/worldline-go/swagger"
)

func Info(version string, provider auth.InfProvider) error {
	return swagger.SetInfo(
		swagger.WithVersion(version),
		swagger.WithCustom(map[string]interface{}{
			"tokenUrl": provider.GetTokenURLExternal(),
			"authUrl":  provider.GetAuthURLExternal(),
		}),
	)
}

OAuth2Application for service authentication.
OAuth2Implicit for user authentication but need to set implicit flow!
OAuth2Password for user authentication with directly with username and password.
OAuth2AccessCode for user authentication with code, it will redirect to the authUrl to login.

Inside of the general information of server:

// Echo Server
//
// @title Auth Test API
// @description This is a sample server for out Auth library.
//
// @contant.name worldline-go
// @contant.url https://github.com/worldline-go
//
// @securityDefinitions.apikey	ApiKeyAuth
// @in							header
// @name						Authorization
// @description				Description for what is this security definition being used
//
// @securitydefinitions.oauth2.accessCode	OAuth2AccessCode
// @tokenUrl								[[ .Custom.tokenUrl ]]
// @authorizationUrl						[[ .Custom.authUrl ]]
func echoServer(ctx context.Context) error {
    // ...
}

Use OAuth2 tags in the requests

// PostValue return the body
//
// @Summary Post value
// @Description Post value
// @Tags restricted
// @Accept  json
// @Produce  json
// @Success 200 {object} map[string]interface{}
// @Failure 403 {object} map[string]interface{}
// @Failure 404 {object} map[string]interface{}
// @Router /value [post]
// @Security ApiKeyAuth || OAuth2AccessCode
func (API) PostValue(c echo.Context) error {
    // ...
}

All definations

// @securitydefinitions.oauth2.application	OAuth2Application
// @tokenUrl								[[ .Custom.tokenUrl ]]
// @securitydefinitions.oauth2.implicit	OAuth2Implicit
// @authorizationUrl						[[ .Custom.authUrl ]]
// @securitydefinitions.oauth2.password	OAuth2Password
// @tokenUrl								[[ .Custom.tokenUrl ]]
// @securitydefinitions.oauth2.accessCode	OAuth2AccessCode
// @tokenUrl								[[ .Custom.tokenUrl ]]
// @authorizationUrl						[[ .Custom.authUrl ]]

Register Echo

e.GET("/swagger/*", echoSwagger.EchoWrapHandler(func(c *echoSwagger.Config) {
	c.OAuth = &echoSwagger.OAuthConfig{
		ClientId: provider.GetClientIDExternal(),
	}
}))