api/docs.go at main · bjaus/api · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
package api

import (
	"html/template"
	"net/http"
)

// DocsOption configures the docs UI.
type DocsOption func(*docsConfig)

type docsConfig struct {
	title   string
	specURL string
}

// WithDocsTitle sets the page title for the docs UI.
func WithDocsTitle(title string) DocsOption {
	return func(c *docsConfig) {
		c.title = title
	}
}

// ServeDocs serves an interactive API documentation UI at the given path.
// It renders Stoplight Elements pointing at the router's OpenAPI spec.
func (r *Router) ServeDocs(path string, opts ...DocsOption) {
	cfg := &docsConfig{
		title:   r.title,
		specURL: "/openapi.json",
	}
	for _, opt := range opts {
		opt(cfg)
	}

	tmpl := template.Must(template.New("docs").Parse(docsHTML))

	r.mux.HandleFunc("GET "+path, func(w http.ResponseWriter, _ *http.Request) {
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
		//nolint:errcheck,gosec // best-effort template render
		tmpl.Execute(w, cfg)
	})
}

const docsHTML = `<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{{.Title}}</title>
  <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
  <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
</head>
<body>
  <elements-api
    apiDescriptionUrl="{{.SpecURL}}"
    router="hash"
    layout="sidebar"
  />
</body>
</html>`

// Title returns the docs config title (used in the template).
func (c *docsConfig) Title() string { return c.title }

// SpecURL returns the docs config spec URL (used in the template).
func (c *docsConfig) SpecURL() string { return c.specURL }