openapidocs

README

Echo OpenAPI Docs

Echo OpenAPI Docs is a Go library that allows you to use OpenAPI documentation generators in your Echo application. It enables you to easily host interactive API documentation based on OpenAPI specifications.

It supports several generators. Please see the Supported Documentation Generators section. If you are not familiar with OpenAPI, please visit the OpenAPI Specification page.

Installation

go get github.com/kohkimakimoto/echo-openapidocs

Minimum Example

package main

import (
	"github.com/kohkimakimoto/echo-openapidocs"
	"github.com/labstack/echo/v4"
	"log"
)

func main() {
	e := echo.New()

	// Register the GitHub v3 REST API documentation at /docs
	openapidocs.ElementsDocuments(e, "/docs", openapidocs.ElementsConfig{
		SpecUrl:  "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/ghes-3.0/ghes-3.0.yaml",
		Title: "GitHub v3 REST API",
	})

	// Start the server
	if err := e.Start(":8080"); err != nil {
		log.Fatal(err)
	}
}

You can see the documentation at http://localhost:8080/docs.

You can also see other examples in examples/main.go file.

Supported Documentation Generators

Stoplight Elements

Stoplight Elements: Build beautiful, interactive API Docs with embeddable React or Web Components, powered by OpenAPI and Markdown.

// Register the Stoplight Elements documentation with OpenAPI Spec url.
openapidocs.ElementsDocuments(e, "/docs", openapidocs.ElementsConfig{
	// The following is the example for generating the OpenAI API documentation.
	// You can replace the SpecUrl with your OpenAPI Spec url.
	SpecUrl: "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml",
})

The generated documentation looks like this:

You can also specify the OpenAPI Spec as a string.

// Using the `go:embed` directive is a great way to embed the OpenAPI Spec file as a string.
//go:embed openai-openapi.yaml
var OpenAIAPISpec string

// Register the Stoplight Elements documentation with OpenAPI Spec string.
openapidocs.ElementsDocuments(e, "/docs", openapidocs.ElementsConfig{
	Spec: OpenAIAPISpec,
})

The ElementsDocuments function takes a configuration from the ElementsConfig struct. For more details, please refer to the documentation here.

Scalar API Reference

Scalar API Reference: Beautiful API references from OpenAPI/Swagger files ✨

// Register the Scalar documentation with OpenAPI Spec url.
openapidocs.ScalarDocuments(e, "/docs", openapidocs.ScalarConfig{
	// The following is the example for generating the OpenAI API documentation.
	// You can replace the SpecUrl with your OpenAPI Spec url.
	SpecUrl: "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml",
})

The generated documentation looks like this:

You can also specify the OpenAPI Spec as a string.

// Using the `go:embed` directive is a great way to embed the OpenAPI Spec file as a string.
//go:embed openai-openapi.yaml
var OpenAIAPISpec string

// Register the Scalar documentation with OpenAPI Spec string.
openapidocs.ScalarDocuments(e, "/docs", openapidocs.ScalarConfig{
	Spec: OpenAIAPISpec,
})

The ScalarDocuments function takes a configuration from the ScalarConfig struct. For more details, please refer to the documentation here.

Swagger UI

Swagger UI: Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.

// Register the SwaggerUI documentation with OpenAPI Spec url.
openapidocs.SwaggerUIDocuments(e, "/docs", openapidocs.SwaggerUIConfig{
	// The following is the example for generating the OpenAI API documentation.
	// You can replace the SpecUrl with your OpenAPI Spec url.
	SpecUrl: "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml",
})

The generated documentation looks like this:

You can also specify the OpenAPI Spec as a string.

// Using the `go:embed` directive is a great way to embed the OpenAPI Spec file as a string.
//go:embed openai-openapi.yaml
var OpenAIAPISpec string

// Register the SwaggerUI documentation with OpenAPI Spec string.
openapidocs.SwaggerUIDocuments(e, "/docs", openapidocs.SwaggerUIConfig{
	Spec: OpenAIAPISpec,
})

The SwaggerUIDocuments function takes a configuration from the SwaggerUIConfig struct. For more details, please refer to the documentation here.

ReDoc

ReDoc: 📘 OpenAPI/Swagger-generated API Reference Documentation.

// Register the Redoc documentation with OpenAPI Spec url.
openapidocs.RedocDocuments(e, "/docs", openapidocs.RedocConfig{
	// The following is the example for generating the OpenAI API documentation.
	// You can replace the SpecUrl with your OpenAPI Spec url.
	SpecUrl: "https://raw.githubusercontent.com/openai/openai-openapi/master/openapi.yaml",
})

The generated documentation looks like this:

You can also specify the OpenAPI Spec as a string.

// Using the `go:embed` directive is a great way to embed the OpenAPI Spec file as a string.
//go:embed openai-openapi.yaml
var OpenAIAPISpec string

// Register the Redoc documentation with OpenAPI Spec string.
openapidocs.RedocDocuments(e, "/docs", openapidocs.RedocConfig{
	Spec: OpenAIAPISpec,
})

The RedocDocuments function takes a configuration from the RedocConfig struct. For more details, please refer to the documentation here.

Author

Kohki Makimoto kohki.makimoto@gmail.com

License

The MIT License (MIT)

Documentation

Index

• Variables
• func ElementsDocuments(e *echo.Echo, pathPrefix string, config ElementsConfig)
• func ElementsDocumentsHandler(config ElementsConfig) echo.HandlerFunc
• func RedocDocuments(e *echo.Echo, pathPrefix string, config RedocConfig)
• func RedocDocumentsHandler(config RedocConfig) echo.HandlerFunc
• func ScalarDocuments(e *echo.Echo, pathPrefix string, config ScalarConfig)
• func ScalarDocumentsHandler(config ScalarConfig) echo.HandlerFunc
• func SwaggerUIDocuments(e *echo.Echo, pathPrefix string, config SwaggerUIConfig)
• func SwaggerUIDocumentsHandler(config SwaggerUIConfig) echo.HandlerFunc
• type ElementsConfig
• type ElementsLayout
• type ElementsRouter
• type ElementsTryItCredentialsPolicy
• type RedocConfig
• type ScalarConfig
• type ScalarLayout
• type ScalarTheme
• type SwaggerUIConfig

Variables

var DefaultElementsConfig = ElementsConfig{
	Spec:                   "",
	SpecUrl:                "",
	Title:                  "API documentation with Stoplight Elements",
	Template:               defaultElementsTemplate,
	Router:                 ElementsRouterHistory,
	Layout:                 ElementsLayoutSidebar,
	HideInternal:           false,
	HideTryIt:              false,
	HideSchemas:            false,
	HideExport:             false,
	TryItCorsProxy:         "",
	TryItCredentialsPolicy: ElementsTryItCredentialsPolicyOmit,
	Logo:                   "",
}

var DefaultRedocConfig = RedocConfig{
	Spec:                           "",
	SpecUrl:                        "",
	Title:                          "API documentation with Redoc",
	Template:                       defaultRedocTemplate,
	MinCharacterLengthToInitSearch: 0,
}

var DefaultScalarConfig = ScalarConfig{
	Spec:         "",
	SpecUrl:      "",
	Title:        "API documentation with Scalar",
	Template:     defaultScalarTemplate,
	IsEditable:   false,
	ProxyUrl:     "",
	DarkMode:     false,
	Layout:       ScalarLayoutModern,
	Theme:        ScalarThemeDefault,
	HideSidebar:  false,
	SearchHotKey: "",
}

var DefaultSwaggerUIConfig = SwaggerUIConfig{
	Spec:               "",
	SpecUrl:            "",
	Title:              "API documentation with Swagger UI",
	Template:           defaultSwaggerUITemplate,
	DeepLinking:        false,
	DisplayOperationId: false,
}

Functions

func ElementsDocuments

func ElementsDocuments(e *echo.Echo, pathPrefix string, config ElementsConfig)

ElementsDocuments registers a handler to serve the OpenAPI documentation with Stoplight Elements.

func ElementsDocumentsHandler

func ElementsDocumentsHandler(config ElementsConfig) echo.HandlerFunc

ElementsDocumentsHandler returns an echo.HandlerFunc to serve the OpenAPI documentation with Stoplight Elements.

func RedocDocuments

func RedocDocuments(e *echo.Echo, pathPrefix string, config RedocConfig)

func RedocDocumentsHandler

func RedocDocumentsHandler(config RedocConfig) echo.HandlerFunc

func ScalarDocuments

func ScalarDocuments(e *echo.Echo, pathPrefix string, config ScalarConfig)

ScalarDocuments registers a handler to serve the OpenAPI documentation with Scalar.

func ScalarDocumentsHandler

func ScalarDocumentsHandler(config ScalarConfig) echo.HandlerFunc

ScalarDocumentsHandler returns an echo.HandlerFunc to serve the OpenAPI documentation with Scalar.

func SwaggerUIDocuments

func SwaggerUIDocuments(e *echo.Echo, pathPrefix string, config SwaggerUIConfig)

SwaggerUIDocuments registers a handler for serving Swagger UI documents.

func SwaggerUIDocumentsHandler

func SwaggerUIDocumentsHandler(config SwaggerUIConfig) echo.HandlerFunc

Types

type ElementsConfig

type ElementsConfig struct {
	// Spec is the OpenAPI specification.
	Spec string
	// SpecUrl is the URL of the OpenAPI specification. If Spec is not empty, SpecUrl is ignored.
	SpecUrl string
	// Title is the title of the page.
	Title string
	// Template is a template string for rendering the page with html/template.
	Template string

	// Router is the Elements `router` configuration.
	Router ElementsRouter
	// Layout is the Elements `layout` configuration.
	Layout ElementsLayout
	// HideInternal is the Elements `hideInternal` configuration.
	HideInternal bool
	// HideTryIt is the Elements `hideTryIt` configuration.
	HideTryIt bool
	// HideSchemas is the Elements `hideSchemas` configuration.
	HideSchemas bool
	// HideExport is the Elements `hideExport` configuration.
	HideExport bool
	// TryItCorsProxy is the Elements `tryItCorsProxy` configuration.
	TryItCorsProxy string
	// TryItCredentialsPolicy is the Elements `tryItCredentialsPolicy` configuration.
	TryItCredentialsPolicy ElementsTryItCredentialsPolicy
	// Logo is the Elements `logo` configuration.
	Logo string
}

ElementsConfig is the configuration for ElementsDocumentsHandler to generate the OpenAPI documentation with Stoplight Elements. Some fields are Elements configuration options. See https://github.com/stoplightio/elements/blob/main/docs/getting-started/elements/elements-options.md

type ElementsLayout

type ElementsLayout string

const (
	ElementsLayoutSidebar    ElementsLayout = "sidebar"
	ElementsLayoutResponsive ElementsLayout = "responsive"
	ElementsLayoutStacked    ElementsLayout = "stacked"
)

type ElementsRouter

type ElementsRouter string

const (
	ElementsRouterHash    ElementsRouter = "hash"
	ElementsRouterHistory ElementsRouter = "history"
	ElementsRouterMemory  ElementsRouter = "memory"
)

type ElementsTryItCredentialsPolicy

type ElementsTryItCredentialsPolicy string

const (
	ElementsTryItCredentialsPolicyOmit ElementsTryItCredentialsPolicy = "omit"
	ElementsTryItCredentialsInclude    ElementsTryItCredentialsPolicy = "include"
	ElementsTryItCredentialsSameOrigin ElementsTryItCredentialsPolicy = "same-origin"
)

type RedocConfig

type RedocConfig struct {
	// Spec is the OpenAPI specification.
	Spec string
	// SpecUrl is the URL of the OpenAPI specification. If Spec is not empty, SpecUrl is ignored.
	SpecUrl string
	// Title is the title of the page.
	Title string
	// Template is a template string for rendering the page with html/template.
	Template string

	// DisableSearch is the Redoc `disableSearch` configuration.
	DisableSearch bool
	// MinCharacterLengthToInitSearch is the Redoc `minCharacterLengthToInitSearch` configuration.
	MinCharacterLengthToInitSearch int
}

RedocConfig is the configuration for RedocDocumentsHandler to generate the OpenAPI documentation with Redoc. Some fields are Redoc configuration options. See https://github.com/Redocly/redoc/blob/main/docs/config.md

type ScalarConfig

type ScalarConfig struct {
	// Spec is the OpenAPI specification.
	Spec string
	// SpecUrl is the URL of the OpenAPI specification. If Spec is not empty, SpecUrl is ignored.
	SpecUrl string
	// Title is the title of the page.
	Title string
	// Template is a template string for rendering the page with html/template.
	Template string

	// IsEditable is the Scalar `isEditable` configuration.
	IsEditable bool
	// ProxyUrl is the Scalar `proxyUrl` configuration.
	ProxyUrl string
	// DarkMode is the Scalar `darkMode` configuration.
	DarkMode bool
	// Layout is the Scalar `layout` configuration.
	Layout ScalarLayout
	// Theme is the Scalar `theme` configuration.
	Theme ScalarTheme
	// HideSidebar is the inverse of the Scalar `showSidebar` configuration.
	// If HideSidebar is true, the `showSidebar` configuration is false.
	// Scalar has a default value of `showSidebar` as true, so if you want to hide the sidebar, set this value to true.
	HideSidebar bool
	// SearchHotKey is the Scalar `searchHotKey` configuration.
	SearchHotKey string
}

ScalarConfig is the configuration for ScalarDocumentsHandler to generate the OpenAPI documentation with Scalar. Some fields are Scalar configuration options. See https://github.com/scalar/scalar?tab=readme-ov-file#configuration

type ScalarLayout

type ScalarLayout string

const (
	ScalarLayoutModern  ScalarLayout = "modern"
	ScalarLayoutClassic ScalarLayout = "classic"
)

type ScalarTheme

type ScalarTheme string

ScalarTheme is the Scalar theme configuration. https://github.com/scalar/scalar?tab=readme-ov-file#themes

const (
	ScalarThemeAlternate  ScalarTheme = "alternate"
	ScalarThemeDefault    ScalarTheme = "default"
	ScalarThemeMoon       ScalarTheme = "moon"
	ScalarThemePurple     ScalarTheme = "purple"
	ScalarThemeSolarized  ScalarTheme = "solarized"
	ScalarThemeBluePlanet ScalarTheme = "bluePlanet"
	ScalarThemeSaturn     ScalarTheme = "saturn"
	ScalarThemeMars       ScalarTheme = "mars"
	ScalarThemeDeepSpace  ScalarTheme = "deepSpace"
	ScalarThemeNone       ScalarTheme = "none"
)

type SwaggerUIConfig

type SwaggerUIConfig struct {
	// Spec is the OpenAPI specification.
	Spec string
	// SpecUrl is the URL of the OpenAPI specification. If Spec is not empty, SpecUrl is ignored.
	SpecUrl string
	// Title is the title of the page.
	Title string
	// Template is a template string for rendering the page with html/template.
	Template string

	// DeepLinking is the Swagger UI `deepLinking` configuration.
	DeepLinking bool
	// DisplayOperationId is the Swagger UI `DisplayOperationId` configuration.
	DisplayOperationId bool
}

SwaggerUIConfig is the configuration for SwaggerUIDocumentsHandler to generate the OpenAPI documentation with Swagger UI. Some fields are Swagger UI configuration options. See https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md