mvrilo/go-redoc

go-redoc is an embedded OpenAPI/Swagger documentation ui for Go using ReDoc

go-redoc

go-redoc is an embedded OpenAPI documentation ui for Go using ReDoc and Go's 1.16+'s embed package, with middleware implementations for: net/http, gin, fiber, and echo.

The template is based on the ReDoc's bundle template with the script already placed in the html instead of depending on a CDN.

This package does not generate openapi spec file. Check this example for using code generation with swag.

Usage

import "github.com/mvrilo/go-redoc"

...

doc := redoc.Redoc{
    Title:       "Example API",
    Description: "Example API Description",
    SpecFile:    "./openapi.json", // "./openapi.yaml"
    SpecPath:    "/openapi.json",  // "/openapi.yaml"
    DocsPath:    "/docs",
}

• net/http

import (
	"net/http"
	"github.com/mvrilo/go-redoc"
)

...

http.ListenAndServe(address, doc.Handler())

• gin

import (
	"github.com/gin-gonic/gin"
	"github.com/mvrilo/go-redoc"
	ginredoc "github.com/mvrilo/go-redoc/gin"
)

...

r := gin.New()
r.Use(ginredoc.New(doc))

• echo

import (
	"github.com/labstack/echo/v4"
	"github.com/mvrilo/go-redoc"
	echoredoc "github.com/mvrilo/go-redoc/echo"
)

...

r := echo.New()
r.Use(echoredoc.New(doc))

• fiber

import (
	"github.com/gofiber/fiber/v2"
	"github.com/mvrilo/go-redoc"
	fiberredoc "github.com/mvrilo/go-redoc/fiber"
)

...

r := fiber.New()
r.Use(fiberredoc.New(doc))

See examples

go-redoc's Issues

load redoc in a path problem

This is example of my code where I try to load the openapi spec in a certain path. Code is not compiled its just
to show how I did it.

Client struct {
    Router *mux.Router
}

client := &Client{}

doc := redoc.Redoc{
	Title:       "",
	Description: "",
	SpecFile:    "./api.yaml",
	SpecPath:    "/api.yaml",
        DocsPath:    "/docs",
}


client.Router.HandleFunc("/hello",HelloHandlerFunc).Methods(http.MethodGet)
client.Router.HandleFunc("/openapi",doc.Handler).Methods(http.MethodGet)

I am trying to access the docs through http://localhost:port/openapi/docs without luck. It just return blank white page

How to create api documentation automatically?

I have added it to fiber but it shows defaults.
How can I add my endpoints in documentation?

gin response code 404

This is my test demo.

package main

import (
	"github.com/gin-gonic/gin"
	"github.com/mvrilo/go-redoc"
	ginredoc "github.com/mvrilo/go-redoc/gin"
)

func main() {
	doc := redoc.Redoc{
		Title:       "Example API",
		Description: "Example API Description",
		SpecFile:    "./openapi.yml",
		SpecPath:    "/openapi.yml",
		DocsPath:    "/docs",
	}

	r := gin.New()
	r.Use(ginredoc.New(doc))

	println("Documentation served at http://127.0.0.1:8000/docs")
	panic(r.Run(":8000"))
}

When I run and visit http://172.28.73.58:8000/docs Page stuck in initialization (172.28.73.58 is my wsl2 ip)


And my gin run window has a warning message
[GIN-debug] [WARNING] Headers were already written. Wanted to override status code 404 with 200
Can you tell me how to solve it? thank

Question: Is there any way to auto generate this openapi.json file using go-redoc or something like that in the near future as a new feature?

About Echo implementation

Hi, I really like the project @mvrilo but there's some suggestions that I think could improve the project, between these are:

• The echo example could be updated for something like this:
  

  The problem with use a middleware for just show documentation is that overwrites all other endpoints.

  

• Other things that I'm sure that goes well to the package is the json/yaml tags for the structs, more than nothing because normally the HTTP Servers have configuration files and directly set everything in that configuration file sounds good.

• Another improvement could be the favicon.ico implementation, in the same way the openapi.yaml is provided in my case.

I don't know if I can open a merge request to make these changes, ready to hear your opinion, me.

net/http not working with mux routers

Registering the net/http handler under a mux router causes a 404 error serving de docs

Using the following code:

func RunInternal() error {
	internal := mux.NewRouter()
	internal.HandleFunc("/health", health.GetHealth().Handler)

	doc := redoc.Redoc{
		Title:       "API Docs",
		Description: "API documentation",
		SpecFile:    "./api/openapi-spec/openapi.yaml",
		SpecPath:    "/openapi.yaml",
		DocsPath:    "/docs",
	}

	internal.HandleFunc("/docs", doc.Handler())

	return http.ListenAndServe(":8079", internal)
}