Merge pull request #336 from danielgtaylor/api-docs-customiztion

docs: API documentation customization
danielgtaylor · Mar 26, 2024 · f160410 · f160410
2 parents 9fc92df + 1ad1ff1
commit f160410
Show file tree

Hide file tree

Showing 6 changed files with 140 additions and 0 deletions.
diff --git a/docs/docs/features/api-docs.md b/docs/docs/features/api-docs.md
@@ -0,0 +1,139 @@
+---
+description: Customizing the generated API documentation using third-party tools like Stoplight Elements, Scalar Docs, and SwaggerUI.
+---
+
+# Generated API Documentation
+
+## Generated API Docs { .hidden }
+
+Huma uses the OpenAPI spec to generate interactive API documentation using third-party tools. By default, [Stoplight Elements](https://stoplight.io/open-source/elements) is used to render the documentation at the API's `config.DocsPath` which defaults to `/docs`.
+
+![Stoplight Elements](./elements.png)
+
+!!! info "Disabling the Docs"
+
+    You can disable the built-in documentation by setting `config.DocsPath` to an empty string.
+
+## Customizing Documentation
+
+You can customize the generated documentation by providing your own renderer function to the API adapter or by using the underlying router directly.
+
+### Stoplight Elements
+
+You can customize the default docs by providing your own HTML so you can set the layout, styles, colors, etc as needed.
+
+```go title="code.go"
+router := chi.NewRouter()
+config := huma.DefaultConfig("Docs Example", "1.0.0")
+config.DocsPath = ""
+
+api := humachi.New(router, config)
+
+router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html")
+	w.Write([]byte(`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="referrer" content="same-origin" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
+    <title>Elements in HTML</title>
+    <!-- Embed elements Elements via Web Component -->
+    <link href="https://unpkg.com/@stoplight/[email protected]/styles.min.css" rel="stylesheet" />
+    <script src="https://unpkg.com/@stoplight/[email protected]/web-components.min.js"
+            integrity="sha256-yIhuSFMJJ6mp2XTUAb4SiSYneP3Qav8Uu+7NBhGJW5A="
+            crossorigin="anonymous"></script>
+  </head>
+  <body style="height: 100vh;">
+    <elements-api
+      apiDescriptionUrl="/openapi.yaml"
+      router="hash"
+      layout="stacked"
+      tryItCredentialsPolicy="same-origin"
+    />
+  </body>
+</html>`))
+})
+```
+
+![Stoplight Elements Stacked](./elements-stacked.png)
+
+### Scalar Docs
+
+[Scalar Docs](https://github.com/scalar/scalar?tab=readme-ov-file#readme) provide a featureful and customizable API documentation experience that feels similar to Postman in your browser.
+
+```go title="code.go"
+router := chi.NewRouter()
+config := huma.DefaultConfig("Docs Example", "1.0.0")
+config.DocsPath = ""
+
+api := humachi.New(router, config)
+
+router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html")
+	w.Write([]byte(`<!doctype html>
+<html>
+  <head>
+    <title>API Reference</title>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      data-url="/openapi.json"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>`))
+})
+```
+
+![Scalar Docs](./scalar.png)
+
+### SwaggerUI
+
+[SwaggerUI](https://github.com/swagger-api/swagger-ui#readme) is an older but proven documentation generator that is widely used in the industry. It provides a more traditional API documentation experience.
+
+```go title="code.go"
+router := chi.NewRouter()
+config := huma.DefaultConfig("Docs Example", "1.0.0")
+config.DocsPath = ""
+
+api := humachi.New(router, config)
+
+router.Get("/docs", func(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "text/html")
+	w.Write([]byte(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="description" content="SwaggerUI" />
+  <title>SwaggerUI</title>
+  <link rel="stylesheet" href="https://unpkg.com/[email protected]/swagger-ui.css" />
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script src="https://unpkg.com/[email protected]/swagger-ui-bundle.js" crossorigin></script>
+<script>
+  window.onload = () => {
+    window.ui = SwaggerUIBundle({
+      url: '/openapi.json',
+      dom_id: '#swagger-ui',
+    });
+  };
+</script>
+</body>
+</html>`))
+})
+```
+
+![SwaggerUI](./swaggerui.png)
+
+## Dive Deeper
+
+-   Reference
+    -   [`huma.Config`](https://pkg.go.dev/github.com/danielgtaylor/huma/v2#Config) the API config
+    -   [`huma.DefaultConfig`](https://pkg.go.dev/github.com/danielgtaylor/huma/v2#DefaultConfig) the default API config
diff --git a/docs/docs/features/elements-stacked.png b/docs/docs/features/elements-stacked.png
diff --git a/docs/docs/features/elements.png b/docs/docs/features/elements.png
diff --git a/docs/docs/features/scalar.png b/docs/docs/features/scalar.png
diff --git a/docs/docs/features/swaggerui.png b/docs/docs/features/swaggerui.png
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -28,6 +28,7 @@ nav:
           - "Service CLI": features/cli.md
       - "OpenAPI & JSON Schema":
           - "Config & OpenAPI": features/openapi-generation.md
+          - "Generated API Docs": features/api-docs.md
           - "JSON Schema & Registry": features/json-schema-registry.md
           - "Schema Customization": features/schema-customization.md
           - "Model Validation": features/model-validation.md