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 [email protected]

License

The MIT License (MIT)