feat: add swagger API example

Author: alexeagle

BUILD.bazel

@@ -65,10 +65,12 @@ docs_index(
     srcs = [
         "@rules_docs_e2e_git_last_updated//:docs",
         "@rules_docs_e2e_smoke//:docs",
+        "@rules_docs_examples_swagger//:docs",
     ],
     nav = {
         "@rules_docs_e2e_smoke//:docs": "e2e/smoke",
         "@rules_docs_e2e_git_last_updated//:docs": "e2e/git_last_updated",
+        "@rules_docs_examples_swagger//:docs": "examples/swagger",
     },
     title = "examples",
 )

MODULE.bazel

@@ -39,18 +39,20 @@ docgen.mkdocs(
 )
 use_repo(docgen, "mkdocs")
 
-E2E_FOLDERS = [
-    "git_last_updated",
-    "smoke",
+NESTED_MODULES = [
+    "e2e/git_last_updated",
+    "e2e/smoke",
+    "examples/swagger",
 ]
 
 [
     [
-        bazel_dep(name = "rules_docs_e2e_%s" % folder, version = "0.0.0", dev_dependency = True),
+        bazel_dep(name = "rules_docs_%s" % escaped_folder, version = "0.0.0", dev_dependency = True),
         local_path_override(
-            module_name = "rules_docs_e2e_%s" % folder,
-            path = "e2e/%s" % folder,
+            module_name = "rules_docs_%s" % escaped_folder,
+            path = folder,
         ),
     ]
-    for folder in E2E_FOLDERS
+    for folder in NESTED_MODULES
+    for escaped_folder in [folder.replace("/", "_")]
 ]

MODULE.bazel.lock

@@ -0,0 +1,53 @@
+
+load("@rules_docs//docgen:defs.bzl", "docs")
+load("@mkdocs//:defs.bzl", "mkdocs_build", "mkdocs_config", "mkdocs_serve")
+load("@rules_python//python:pip.bzl", "compile_pip_requirements")
+
+compile_pip_requirements(
+    name = "requirements",
+    src = "pyproject.toml",
+    requirements_txt = "requirements.txt",
+)
+
+docs(
+    name = "other_docs",
+    entry = "api-reference.md",
+    data = ["openapi.yaml"],
+    readme_content = "API Reference",
+)
+
+# Main documentation configuration
+docs(
+    name = "docs",
+    nav = {
+        "README.md": "Home",
+        ":other_docs": "API Reference (Redoc)",
+    },
+    rewrite_path = "examples/swagger",
+    visibility = ["//visibility:public"],
+)
+
+# Generate mkdocs configuration
+mkdocs_config(
+    name = "mkdocs_config",
+    docs = ":docs",
+    mkdocs_base = "mkdocs.tpl.yaml",
+)
+
+# Build documentation site
+mkdocs_build(
+    name = "mkdocs",
+    config = ":mkdocs_config",
+    docs = [":docs"],
+    site_dir = "site",
+    visibility = ["//visibility:public"],
+)
+
+# Serve documentation locally for development
+# Recommended: run with ibazel for auto-reload on changes
+mkdocs_serve(
+    name = "mkdocs.serve",
+    config = ":mkdocs_config",
+    docs = [":docs"],
+    visibility = ["//visibility:public"],
+)

examples/swagger/BUILD

@@ -0,0 +1,24 @@
+module(name = "rules_docs_examples_swagger")
+
+bazel_dep(name = "rules_docs")
+
+local_path_override(
+    module_name = "rules_docs",
+    path = "../..",
+)
+
+bazel_dep(name = "rules_python", version = "1.7.0")
+
+# Configure Python and pip dependencies
+pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
+pip.parse(
+    hub_name = "mkdocs_deps",
+    python_version = "3.11",
+    requirements_lock = "//:requirements.txt",
+)
+use_repo(pip, "mkdocs_deps")
+
+# Configure docgen with mkdocs plugins
+docgen = use_extension("@rules_docs//docgen:extensions.bzl", "docgen")
+docgen.mkdocs(plugins = ["mkdocs-redoc-tag"], pypi_hub = "@mkdocs_deps")
+use_repo(docgen, "mkdocs")

examples/swagger/MODULE.bazel

@@ -0,0 +1,37 @@
+# Swagger/OpenAPI Example
+
+This directory contains an OpenAPI 3.0 specification file that demonstrates rich API documentation suitable for use with SwaggerUI.
+We then run Bazel actions to run the docgen tool and stitch into the parent repository's documentation site.
+
+## Files
+
+- `openapi.yaml` - Complete OpenAPI 3.0 specification for a Task Management API
+
+## Features Demonstrated
+
+The OpenAPI specification includes:
+
+- **Comprehensive API Documentation**: Rich descriptions for all endpoints, parameters, and schemas
+- **Multiple Endpoints**: CRUD operations for tasks, projects, and users
+- **Request/Response Examples**: Multiple examples for different use cases
+- **Detailed Schemas**: Well-documented data models with validation rules
+- **Error Responses**: Standardized error response formats
+- **Authentication**: Bearer token authentication scheme
+- **Pagination**: Pagination support for list endpoints
+- **Filtering & Sorting**: Query parameters for filtering and sorting results
+
+## Viewing with SwaggerUI
+
+Run `bazel run mkdocs.serve`
+
+Then open http://localhost:8080
+
+## API Overview
+
+The Task Management API provides:
+
+- **Tasks**: Create, read, update, and delete tasks with status, priority, assignments, and due dates
+- **Projects**: Organize tasks into projects
+- **Users**: Manage users who can be assigned to tasks
+
+All endpoints require Bearer token authentication and return JSON responses.

examples/swagger/MODULE.bazel.lock

@@ -0,0 +1 @@
+<redoc src="./openapi.yaml"></redoc>

examples/swagger/README.md

@@ -0,0 +1,6 @@
+site_name: Swagger Example
+repo_url: https://github.com/jacobshirley/rules_docs/tree/main/examples/swagger
+docs_dir: docs
+site_dir: site
+plugins:
+    - redoc-tag