diff --git a/Guide/json-api.markdown b/Guide/json-api.markdown
index cb58be922..8814f3939 100644
--- a/Guide/json-api.markdown
+++ b/Guide/json-api.markdown
@@ -412,7 +412,9 @@ instance View ShowView where
     |]
 
 instance JsonView ShowView where
-    json ShowView { post } = toJSON post
+    type JsonResponse ShowView = Post
+
+    jsonTyped ShowView { post } = post
 ```
 
 When a browser requests the page (sending `Accept: text/html`), it gets the HTML response. When an API client requests it with `Accept: application/json`, it gets JSON. You can test this:
diff --git a/Guide/routing.markdown b/Guide/routing.markdown
index e4128f4ad..0bc4af9fe 100644
--- a/Guide/routing.markdown
+++ b/Guide/routing.markdown
@@ -26,6 +26,60 @@ instance FrontController WebApplication where
 
 Now you can open e.g. `/Posts` to access the `PostsAction`.
 
+If you want a pure `AutoRoute` controller to also appear in the generated OpenAPI document, define its actions with the inspectable `endpoint` DSL and mount it using [`documentRoute`](https://ihp.digitallyinduced.com/api-docs/IHP-RouterSupport.html#v:documentRoute):
+
+```haskell
+instance FrontController WebApplication where
+    controllers =
+        [ -- ...
+        , documentRoute @PostsController
+        ]
+```
+
+`documentRoute` derives paths, methods and parameters from `AutoRoute`. Response schemas, request bodies and operation metadata come from the `endpoint` definitions next to the controller handlers.
+
+Simple `customRoutes` / `customPathTo` overrides are supported when `customPathTo` returns a path backed by `customRoutes` and all action fields appear in the path. If IHP cannot prove this during OpenAPI generation, `buildOpenApi` fails with an `OpenApiGenerationException` instead of silently generating stale docs. Lower-level parser routes stay undocumented.
+
+You can then build the OpenAPI document from the mounted router tree:
+
+```haskell
+spec :: Value
+spec = buildOpenApi RootApplication
+```
+
+[`buildOpenApi`](https://ihp.digitallyinduced.com/api-docs/IHP-OpenApiSupport.html#v:buildOpenApi) traverses the same front controller structure that serves requests, so nested `mountFrontController` prefixes are reflected in the generated paths.
+
+If you also want to serve the generated specification and a Swagger UI for it, mount [`swaggerUi`](https://ihp.digitallyinduced.com/api-docs/IHP-OpenApiSupport.html#v:swaggerUi) in the same front controller:
+
+```haskell
+instance FrontController WebApplication where
+    controllers =
+        [ documentRoute @PostsController
+        , swaggerUi
+        ]
+```
+
+This serves:
+
+- `/api-docs` with the Swagger UI
+- `/api-docs/openapi.json` with the generated OpenAPI 3 document
+
+If you want a different path or page title, use [`swaggerUiWithOptions`](https://ihp.digitallyinduced.com/api-docs/IHP-OpenApiSupport.html#v:swaggerUiWithOptions):
+
+```haskell
+instance FrontController WebApplication where
+    controllers =
+        [ documentRoute @PostsController
+        , swaggerUiWithOptions
+            ((defaultSwaggerUiOptions @WebApplication)
+                { swaggerUiPath = "/docs"
+                , swaggerUiTitle = Just "Posts API Docs"
+                })
+        ]
+```
+
+The Swagger UI route stays tied to the same front controller where you mount it, so the UI and the JSON specification are generated from the actual Haskell routes in that router. If you want to document your full root application including outer `mountFrontController` prefixes, mount `swaggerUi` in the root front controller. By default the HTML shell loads the Swagger UI assets from the `swagger-ui-dist` CDN; if you need different asset URLs you can override them in `SwaggerUiOptions`.
+
 ## Changing the Start Page / Home Page
 
 You can define a custom start page action using the [`startPage`](https://ihp.digitallyinduced.com/api-docs/IHP-RouterSupport.html#v:startPage) function like this:
@@ -208,6 +262,8 @@ With this setup:
 
 The `customRoutes` parser is tried first, before the auto-generated routes. If it doesn't match, the auto-generated routes are tried as usual. Return `Nothing` from `customPathTo` for any action that should use the default URL generation.
 
+When mounted with `documentRoute`, this basic custom route is included in the OpenAPI document as `/posts/{postId}`. IHP verifies that the generated `customPathTo` path is accepted by `customRoutes`; unsupported custom paths fail OpenAPI generation with a clear error.
+
 ## Custom Routing
 
 Sometimes you have special needs for your routing. For this case, IHP provides a lower-level routing API on which [`AutoRoute`](https://ihp.digitallyinduced.com/api-docs/IHP-RouterSupport.html#t:AutoRoute) is built.
diff --git a/Guide/view.markdown b/Guide/view.markdown
index 21b56059a..3267f73f3 100644
--- a/Guide/view.markdown
+++ b/Guide/view.markdown
@@ -462,7 +462,7 @@ document.addEventListener('ihp:unload', () => {
 
 ## JSON
 
-Views that are rendered by calling the [`render`](https://ihp.digitallyinduced.com/api-docs/IHP-Controller-Render.html#v:render) function can also respond with JSON.
+Views that are rendered by calling the [`renderHtmlOrJson`](https://ihp.digitallyinduced.com/api-docs/IHP-Controller-Render.html#v:renderHtmlOrJson) function can respond with either HTML or JSON based on the request `Accept` header.
 
 Let's say we have a normal HTML view that renders all posts for our blog app:
 
@@ -491,41 +491,74 @@ instance View IndexView where
     |]
 ```
 
-We can add a JSON output for all blog posts by adding a [`json`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewSupport.html#v:json) function to this:
+We can add a JSON output for all blog posts by defining a typed [`JsonResponse`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewSupport.html#t:JsonView) payload and implementing [`jsonTyped`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewSupport.html#v:jsonTyped) in a `JsonView` instance:
 
 ```haskell
-import Data.Aeson -- <--- Add this import at the top of the file
+{-# LANGUAGE DeriveGeneric #-}
 
+import Data.Aeson
+import GHC.Generics (Generic)
+
+data PostPayload = PostPayload
+    { id :: !(Id Post)
+    , title :: !Text
+    , body :: !Text
+    }
+    deriving (Eq, Show, Generic)
+
+instance ToJSON PostPayload
+```
+
+```haskell
 instance View IndexView where
     html IndexView { .. } = [hsx|
         ...
     |]
 
-    json IndexView { .. } = toJSON posts -- <---- The new json render function
+instance JsonView IndexView where
+    type JsonResponse IndexView = [PostPayload]
+
+    jsonTyped IndexView { .. } =
+        posts
+            |> map (\post -> PostPayload
+                { id = post.id
+                , title = post.title
+                , body = post.body
+                })
 ```
 
-In the above code, our [`json`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewSupport.html#v:json) function has access to all arguments passed to the view. Here we call [`toJSON`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewPrelude.html#v:toJSON), which is provided by the [aeson](https://hackage.haskell.org/package/aeson) Haskell library. This simply encodes all the `posts` given to this view as JSON.
+In the above code, [`jsonTyped`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewSupport.html#v:jsonTyped) has access to all arguments passed to the view, but returns a normal Haskell value instead of raw `Value`. IHP then turns that into JSON automatically using [`toJSON`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewPrelude.html#v:toJSON).
 
-Additionally we need to define a [`ToJSON`](https://ihp.digitallyinduced.com/api-docs/IHP-ViewPrelude.html#t:ToJSON) instance which describes how the `Post` record is going to be transformed to JSON. We need to add this to our view:
+In the controller, use [`renderHtmlOrJson`](https://ihp.digitallyinduced.com/api-docs/IHP-Controller-Render.html#v:renderHtmlOrJson) instead of `render` for actions that should serve both formats:
 
 ```haskell
-instance ToJSON Post where
-    toJSON post = object
-        [ "id" .= post.id
-        , "title" .= post.title
-        , "body" .= post.body
-        ]
+action PostsAction = do
+    posts <- query @Post |> fetch
+    renderHtmlOrJson IndexView { .. }
 ```
 
 The full `Index` View for our `PostsController` looks like this:
 
 ```haskell
 module Web.View.Posts.Index where
+
+{-# LANGUAGE DeriveGeneric #-}
+
 import Web.View.Prelude
 import Data.Aeson
+import GHC.Generics (Generic)
 
 data IndexView = IndexView { posts :: [Post] }
 
+data PostPayload = PostPayload
+    { id :: !(Id Post)
+    , title :: !Text
+    , body :: !Text
+    }
+    deriving (Eq, Show, Generic)
+
+instance ToJSON PostPayload
+
 instance View IndexView where
     html IndexView { .. } = [hsx|
         <nav>
@@ -549,14 +582,16 @@ instance View IndexView where
         </div>
     |]
 
-    json IndexView { .. } = toJSON posts
+instance JsonView IndexView where
+    type JsonResponse IndexView = [PostPayload]
 
-instance ToJSON Post where
-    toJSON post = object
-        [ "id" .= post.id
-        , "title" .= post.title
-        , "body" .= post.body
-        ]
+    jsonTyped IndexView { .. } =
+        posts
+            |> map (\post -> PostPayload
+                { id = post.id
+                , title = post.title
+                , body = post.body
+                })
 
 renderPost post = [hsx|
     <tr>
@@ -568,6 +603,8 @@ renderPost post = [hsx|
 |]
 ```
 
+For dynamic or unstructured JSON responses, keep the escape hatch explicit by using `Value` as the response type and returning it from `jsonTyped`. Documented OpenAPI actions should prefer concrete payload types with matching `ToJSON` and `ToSchema` instances.
+
 ### Getting JSON responses
 
 When you open the `PostsAction` at `/Posts` in your browser you will still get the HTML output. [This is because IHP uses the browser `Accept` header to respond in the best format for the browser which is usually HTML.](https://en.wikipedia.org/wiki/Content_negotiation)
@@ -593,6 +630,80 @@ curl http://localhost:8000/Posts -H 'Accept: application/json'
 [{"body":"This is a test json post","id":"d559cd60-e36e-40ef-b69a-d651e3257dc9","title":"Hello World!"}]
 ```
 
+### OpenAPI schemas for JSON views
+
+If you want an AutoRoute controller action to appear in the generated OpenAPI document, keep the OpenAPI contract next to the handler using inspectable action definitions.
+Add a [`ToSchema`](https://ihp.digitallyinduced.com/api-docs/IHP-OpenApiSupport.html#t:ToSchema) instance for the typed JSON payload, then declare the response view and metadata directly in `action`. When the `handle` callback takes a typed argument, IHP decodes that JSON request body and documents the same type in OpenAPI:
+
+```haskell
+{-# LANGUAGE DeriveGeneric #-}
+{-# LANGUAGE TypeApplications #-}
+
+import GHC.Generics (Generic)
+
+data PostPayload = PostPayload
+    { id :: !(Id Post)
+    , title :: !Text
+    }
+    deriving (Eq, Show, Generic)
+
+instance ToJSON PostPayload
+instance ToSchema PostPayload
+
+data CreatePostRequest = CreatePostRequest
+    { title :: !Text
+    }
+    deriving (Eq, Show, Generic)
+
+instance FromJSON CreatePostRequest
+instance ToSchema CreatePostRequest
+
+instance View IndexView where
+    html IndexView { .. } = [hsx|...|]
+
+instance JsonView IndexView where
+    type JsonResponse IndexView = [PostPayload]
+    jsonTyped IndexView { .. } = posts |> map (\post -> PostPayload { id = post.id, title = post.title })
+
+instance Controller PostsController where
+    type ControllerAction PostsController = ActionDefinition PostsController
+
+    action PostsAction =
+        endpoint
+            |> responseView @IndexView
+            |> summary "List all posts"
+            |> handle do
+                posts <- query @Post |> fetch
+                pure IndexView { .. }
+
+    action CreatePostAction =
+        endpoint
+            |> responseView @IndexView
+            |> summary "Create post"
+            |> handle \(body :: CreatePostRequest) -> do
+                _ <- newRecord @Post
+                    |> set #title body.title
+                    |> createRecord
+                posts <- query @Post |> fetch
+                pure IndexView { .. }
+
+    action HtmlOnlyAction =
+        legacyAction do
+            render HtmlOnlyView
+```
+
+Mount the controller with [`documentRoute`](https://ihp.digitallyinduced.com/api-docs/IHP-RouterSupport.html#v:documentRoute) to include its inspectable actions in the generated OpenAPI document:
+
+```haskell
+instance FrontController WebApplication where
+    controllers =
+        [ documentRoute @PostsController
+        , swaggerUi
+        ]
+```
+
+In this form, `handle` decodes the typed request body before the handler runs, and the inferred body type is the type used in the OpenAPI request schema. The handler must return the same view type declared by `responseView`. Actions wrapped in `legacyAction` are executed normally and omitted from the OpenAPI document.
+
 ### Advanced: Rendering JSON directly from actions
 
 When you are building an API and your action is only responding with JSON (so no HTML is expected), you can respond with your JSON directly from the controller using [`renderJson`](https://ihp.digitallyinduced.com/api-docs/IHP-Controller-Render.html#v:renderJson):
diff --git a/ihp-ide/IHP/IDE/CodeGen/ApplicationGenerator.hs b/ihp-ide/IHP/IDE/CodeGen/ApplicationGenerator.hs
index ccfd4e9aa..8e99945a6 100644
--- a/ihp-ide/IHP/IDE/CodeGen/ApplicationGenerator.hs
+++ b/ihp-ide/IHP/IDE/CodeGen/ApplicationGenerator.hs
@@ -42,6 +42,8 @@ generateGenericApplication applicationName =
                 <> "instance FrontController " <> applicationName <> "Application where\n"
                 <> "    controllers = \n"
                 <> "        [ startPage WelcomeAction\n"
+                <> "        -- Use documentRoute @YourController instead of parseRoute @YourController\n"
+                <> "        -- when you want OpenAPI docs derived from AutoRoute.\n"
                 <> "        -- Generator Marker\n"
                 <> "        ]\n\n"
                 <> "instance InitControllerContext " <> applicationName <> "Application where\n"
diff --git a/ihp/IHP/AutoRefresh.hs b/ihp/IHP/AutoRefresh.hs
index 6c2b077bf..b999b0ef0 100644
--- a/ihp/IHP/AutoRefresh.hs
+++ b/ihp/IHP/AutoRefresh.hs
@@ -66,7 +66,7 @@ autoRefresh runAction = do
 
             case autoRefreshState of
                 Just (AutoRefreshEnabled {}) -> do
-                    -- When this function calls the 'action ?theAction' in the other case
+                    -- When this function calls the current controller action in the other case
                     -- we will evaluate this branch
                     runAction
                 _ -> do
@@ -92,7 +92,7 @@ autoRefresh runAction = do
                                 let ?context = controllerContext
                                 let ?request = originalRequest
                                 let ?respond = respond
-                                action ?theAction
+                                runControllerAction (action ?theAction)
                                 ) waiRequest waiRespond
 
                     -- We save the allowed session ids to the session cookie to only grant a client access
diff --git a/ihp/IHP/Controller/ActionDefinition.hs b/ihp/IHP/Controller/ActionDefinition.hs
new file mode 100644
index 000000000..54dfc04d9
--- /dev/null
+++ b/ihp/IHP/Controller/ActionDefinition.hs
@@ -0,0 +1,284 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE FlexibleInstances #-}
+{-# LANGUAGE FunctionalDependencies #-}
+{-# LANGUAGE GADTs #-}
+{-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE RankNTypes #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+module IHP.Controller.ActionDefinition
+    ( ActionDefinition (..)
+    , EndpointBuilder
+    , endpoint
+    , requestBodyIsRequired
+    , responseView
+    , summary
+    , description
+    , tags
+    , operationId
+    , successStatus
+    , successResponseDescription
+    , HandleEndpoint (handle)
+    , legacyAction
+    , actionDefinitionDoc
+    ) where
+
+import Data.Aeson qualified as JSON
+import Data.ByteString (ByteString)
+import Data.Data
+import Data.Foldable (asum)
+import Data.Int
+import Data.Maybe (fromMaybe, mapMaybe)
+import Data.OpenApi (ToSchema)
+import Data.String.Conversions (cs)
+import Data.Text (Text)
+import Data.Typeable qualified as Typeable
+import Data.UUID qualified as UUID
+import Data.Word
+import IHP.Controller.Render (renderHtmlOrJsonWithStatusCode)
+import IHP.ControllerSupport
+import IHP.OpenApiSupport.ActionDoc
+import IHP.ViewSupport qualified as ViewSupport
+import Network.HTTP.Types.Header (hContentType)
+import Network.HTTP.Types.Status (Status, status200, status400)
+import Network.Wai (responseLBS)
+import Prelude
+
+-- | Inspectable controller action used by the endpoint DSL.
+--
+-- The documentation part is pure and can be read while generating OpenAPI.
+-- The runner part is executed with the normal controller implicit parameters.
+data ActionDefinition controller = ActionDefinition
+    { actionDefinitionDocFor :: controller -> Maybe (ActionDoc controller)
+    , runActionDefinition :: ControllerAction' controller
+    }
+
+instance RunControllerAction controller (ActionDefinition controller) where
+    runControllerActionDefault = runActionDefinition
+    {-# INLINABLE runControllerActionDefault #-}
+
+instance
+    ( Data controller
+    , Controller controller
+    , ControllerAction controller ~ ActionDefinition controller
+    ) =>
+    HasOpenApiActionDocs controller (ActionDefinition controller)
+    where
+    openApiActionDocs = actionDefinitionDocs @controller
+
+-- | Builder used by 'endpoint', 'responseView' and metadata setters.
+data EndpointBuilder controller view = EndpointBuilder
+    { endpointDocModifiers :: [ActionDoc controller -> ActionDoc controller]
+    , endpointSuccessStatus :: Status
+    }
+
+-- | Starts an inspectable endpoint definition.
+endpoint :: EndpointBuilder controller view
+endpoint =
+    EndpointBuilder
+        { endpointDocModifiers = []
+        , endpointSuccessStatus = status200
+        }
+{-# INLINE endpoint #-}
+
+addEndpointDocModifier ::
+    (ActionDoc controller -> ActionDoc controller) ->
+    EndpointBuilder controller view ->
+    EndpointBuilder controller view
+addEndpointDocModifier modifier endpointBuilder@EndpointBuilder{endpointDocModifiers} =
+    endpointBuilder{endpointDocModifiers = endpointDocModifiers <> [modifier]}
+{-# INLINE addEndpointDocModifier #-}
+
+-- | Overrides whether the OpenAPI request body is required.
+requestBodyIsRequired :: Bool -> EndpointBuilder controller view -> EndpointBuilder controller view
+requestBodyIsRequired required =
+    addEndpointDocModifier (setOpenApiRequestBodyRequired required)
+{-# INLINE requestBodyIsRequired #-}
+
+-- | Declares the view rendered by the endpoint.
+responseView :: forall view controller previousView. EndpointBuilder controller previousView -> EndpointBuilder controller view
+responseView EndpointBuilder{endpointDocModifiers, endpointSuccessStatus} =
+    EndpointBuilder{endpointDocModifiers, endpointSuccessStatus}
+{-# INLINE responseView #-}
+
+-- | Sets the OpenAPI operation summary.
+summary :: Text -> EndpointBuilder controller view -> EndpointBuilder controller view
+summary text =
+    addEndpointDocModifier (setOpenApiSummary text)
+{-# INLINE summary #-}
+
+-- | Sets the OpenAPI operation description.
+description :: Text -> EndpointBuilder controller view -> EndpointBuilder controller view
+description text =
+    addEndpointDocModifier (setOpenApiDescription text)
+{-# INLINE description #-}
+
+-- | Sets the OpenAPI operation tags.
+tags :: [Text] -> EndpointBuilder controller view -> EndpointBuilder controller view
+tags values =
+    addEndpointDocModifier (setOpenApiTags values)
+{-# INLINE tags #-}
+
+-- | Sets the OpenAPI operation id.
+operationId :: Text -> EndpointBuilder controller view -> EndpointBuilder controller view
+operationId text =
+    addEndpointDocModifier (setOpenApiOperationId text)
+{-# INLINE operationId #-}
+
+-- | Sets the documented and rendered success status.
+successStatus :: Status -> EndpointBuilder controller view -> EndpointBuilder controller view
+successStatus status endpointBuilder =
+    addEndpointDocModifier (setOpenApiSuccessStatus status) endpointBuilder{endpointSuccessStatus = status}
+{-# INLINE successStatus #-}
+
+-- | Sets the OpenAPI success response description.
+successResponseDescription :: Text -> EndpointBuilder controller view -> EndpointBuilder controller view
+successResponseDescription text =
+    addEndpointDocModifier (setOpenApiSuccessResponseDescription text)
+{-# INLINE successResponseDescription #-}
+
+buildActionDoc ::
+    forall view controller.
+    ( Data controller
+    , ViewSupport.View view
+    , ViewSupport.JsonView view
+    , Typeable.Typeable view
+    , JSON.ToJSON (ViewSupport.JsonResponse view)
+    , ToSchema (ViewSupport.JsonResponse view)
+    ) =>
+    [ActionDoc controller -> ActionDoc controller] ->
+    EndpointBuilder controller view ->
+    controller ->
+    ActionDoc controller
+buildActionDoc initialDocModifiers EndpointBuilder{endpointDocModifiers} controller =
+    foldl'
+        (\doc modifier -> modifier doc)
+        (actionDoc @view (cs (showConstr (toConstr controller))))
+        (initialDocModifiers <> endpointDocModifiers)
+{-# INLINE buildActionDoc #-}
+
+-- | Finalizes an endpoint definition and records OpenAPI metadata from the handler type.
+class HandleEndpoint controller handler view | handler -> view where
+    -- | Finalizes an endpoint definition with its handler.
+    --
+    -- An @IO view@ handler has no request body. A @body -> IO view@ handler
+    -- decodes that JSON body and uses the same body type for OpenAPI.
+    handle :: handler -> EndpointBuilder controller view -> ActionDefinition controller
+
+instance
+    ( Data controller
+    , ViewSupport.View view
+    , ViewSupport.JsonView view
+    , Typeable.Typeable view
+    , JSON.ToJSON (ViewSupport.JsonResponse view)
+    , ToSchema (ViewSupport.JsonResponse view)
+    ) =>
+    HandleEndpoint controller (IO view) view
+    where
+    handle viewAction builder@EndpointBuilder{endpointSuccessStatus} =
+        ActionDefinition
+            { actionDefinitionDocFor = Just . buildActionDoc @view [] builder
+            , runActionDefinition = viewAction >>= renderHtmlOrJsonWithStatusCode endpointSuccessStatus
+            }
+
+instance
+    {-# OVERLAPPABLE #-}
+    ( Data controller
+    , JSON.FromJSON body
+    , ToSchema body
+    , Typeable.Typeable body
+    , ViewSupport.View view
+    , ViewSupport.JsonView view
+    , Typeable.Typeable view
+    , JSON.ToJSON (ViewSupport.JsonResponse view)
+    , ToSchema (ViewSupport.JsonResponse view)
+    ) =>
+    HandleEndpoint controller (body -> IO view) view
+    where
+    handle viewAction builder@EndpointBuilder{endpointSuccessStatus} =
+        ActionDefinition
+            { actionDefinitionDocFor = Just . buildActionDoc @view [setOpenApiRequestBody @body] builder
+            , runActionDefinition = do
+                rawBody <- getRequestBody
+                case JSON.eitherDecode rawBody of
+                    Left errorMessage ->
+                        respondAndExit
+                            ( responseLBS
+                                status400
+                                [(hContentType, "text/plain")]
+                                (cs ("Invalid JSON request body: " <> errorMessage))
+                            )
+                    Right body ->
+                        viewAction body >>= renderHtmlOrJsonWithStatusCode endpointSuccessStatus
+            }
+
+-- | Wraps a classic controller action in an inspectable controller.
+--
+-- The wrapped action is executed normally and omitted from OpenAPI docs.
+legacyAction :: ControllerAction' controller -> ActionDefinition controller
+legacyAction controllerAction =
+    ActionDefinition
+        { actionDefinitionDocFor = const Nothing
+        , runActionDefinition = controllerAction
+        }
+{-# INLINE legacyAction #-}
+
+-- | Reads the OpenAPI documentation for a concrete action value.
+actionDefinitionDoc :: controller -> ActionDefinition controller -> Maybe (ActionDoc controller)
+actionDefinitionDoc controller ActionDefinition{actionDefinitionDocFor} =
+    actionDefinitionDocFor controller
+{-# INLINE actionDefinitionDoc #-}
+
+-- | Builds OpenAPI docs from the same inspectable action definitions used at runtime.
+actionDefinitionDocs ::
+    forall controller.
+    ( Controller controller
+    , Data controller
+    , ControllerAction controller ~ ActionDefinition controller
+    ) =>
+    [ActionDoc controller]
+actionDefinitionDocs =
+    dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
+        |> mapMaybe (buildDoc . fromConstrB dummyDataValue)
+  where
+    buildDoc controller =
+        let ?context = error "actionDefinitionDocs: endpoint construction must not use ?context"
+            ?modelContext = error "actionDefinitionDocs: endpoint construction must not use ?modelContext"
+            ?theAction = controller
+            ?respond = error "actionDefinitionDocs: endpoint construction must not use ?respond"
+            ?request = error "actionDefinitionDocs: endpoint construction must not use ?request"
+         in actionDefinitionDoc controller (action controller)
+{-# INLINE actionDefinitionDocs #-}
+
+dummyDataValue :: forall value. (Data value) => value
+dummyDataValue =
+    fromMaybe fromFirstConstructor knownDummyValue
+  where
+    knownDummyValue =
+        asum
+            [ Typeable.cast (0 :: Int)
+            , Typeable.cast (0 :: Int8)
+            , Typeable.cast (0 :: Int16)
+            , Typeable.cast (0 :: Int32)
+            , Typeable.cast (0 :: Int64)
+            , Typeable.cast (0 :: Integer)
+            , Typeable.cast (0 :: Word)
+            , Typeable.cast (0 :: Word8)
+            , Typeable.cast (0 :: Word16)
+            , Typeable.cast (0 :: Word32)
+            , Typeable.cast (0 :: Word64)
+            , Typeable.cast ("" :: Text)
+            , Typeable.cast ("" :: ByteString)
+            , Typeable.cast UUID.nil
+            ]
+
+    fromFirstConstructor =
+        case dataTypeConstrs (dataTypeOf (Prelude.undefined :: value)) of
+            constructor : _ -> fromConstrB dummyDataValue constructor
+            [] -> error ("actionDefinitionDocs: cannot build dummy value for " <> show (Typeable.typeRep (Proxy @value)))
+{-# INLINE dummyDataValue #-}
diff --git a/ihp/IHP/Controller/Render.hs b/ihp/IHP/Controller/Render.hs
index 0e2170305..685b08a4d 100644
--- a/ihp/IHP/Controller/Render.hs
+++ b/ihp/IHP/Controller/Render.hs
@@ -14,16 +14,21 @@ import IHP.HSX.Markup (Markup, MarkupM(..))
 import qualified IHP.Controller.Context as Context
 import IHP.Controller.Layout
 import IHP.FlashMessages (consumeFlashMessagesMiddleware)
+import IHP.RouterSupport (validateOpenApiRenderedView)
 
 renderPlain :: (?request :: Request, ?respond :: Respond) => LByteString -> IO ResponseReceived
 renderPlain text = respondWith $ responseLBS status200 [(hContentType, "text/plain")] text
 {-# INLINE renderPlain #-}
 
-respondHtml :: (?request :: Request, ?respond :: Respond) => Markup -> IO ResponseReceived
-respondHtml (Markup builder) = do
+respondHtmlWithStatus :: (?request :: Request, ?respond :: Respond) => Status -> Markup -> IO ResponseReceived
+respondHtmlWithStatus status (Markup builder) = do
         -- Pass the Builder directly to WAI, avoiding the intermediate lazy
         -- ByteString allocation that responseLBS would require.
-        respondWith $ responseBuilder status200 [(hContentType, "text/html; charset=utf-8"), (hConnection, "keep-alive")] builder
+        respondWith $ responseBuilder status [(hContentType, "text/html; charset=utf-8"), (hConnection, "keep-alive")] builder
+{-# INLINE respondHtmlWithStatus #-}
+
+respondHtml :: (?request :: Request, ?respond :: Respond) => Markup -> IO ResponseReceived
+respondHtml = respondHtmlWithStatus status200
 {-# INLINE respondHtml #-}
 
 respondSvg :: (?request :: Request, ?respond :: Respond) => Markup -> IO ResponseReceived
@@ -65,35 +70,89 @@ renderJson' :: (?request :: Request, ?respond :: Respond) => ResponseHeaders ->
 renderJson' additionalHeaders json = respondWith $ responseLBS status200 ([(hContentType, "application/json")] <> additionalHeaders) (Data.Aeson.encode json)
 {-# INLINE renderJson' #-}
 
+data PolymorphicRender
+    = PolymorphicRender
+        { html :: Maybe (IO ResponseReceived)
+        , json :: Maybe (IO ResponseReceived)
+        }
+
+-- | Can be used to render different responses for html, json, etc. requests based on the Accept header.
+renderPolymorphic :: (?context :: ControllerContext, ?request :: Request, ?respond :: Respond) => PolymorphicRender -> IO ResponseReceived
+renderPolymorphic PolymorphicRender { html, json } = do
+    let acceptHeader = lookup hAccept (?request.requestHeaders)
+    case acceptHeader of
+        Nothing | Just handler <- html -> handler
+        Just h | "text/html" `isPrefixOf` h, Just handler <- html -> handler
+        _ -> do
+            let accept = fromMaybe "text/html" acceptHeader
+            let send406Error = respondWith $ responseLBS status406 [] "Could not find any acceptable response format"
+            let formats = concat
+                    [ case html of
+                        Just handler -> [("text/html", handler)]
+                        Nothing -> []
+                    , case json of
+                        Just handler -> [("application/json", handler)]
+                        Nothing -> []
+                    ]
+            fromMaybe send406Error (Accept.mapAcceptMedia formats accept)
+{-# INLINE renderPolymorphic #-}
+
+polymorphicRender :: PolymorphicRender
+polymorphicRender = PolymorphicRender Nothing Nothing
+
 {-# INLINE render #-}
 render :: forall view. (ViewSupport.View view, ?context :: ControllerContext, ?request :: Request, ?respond :: Respond) => view -> IO ResponseReceived
 render !view = do
     let !currentRequest = ?request
     renderHtmlView currentRequest view
 
--- | Renders HTML or JSON based on the request's Accept header.
--- Requires both 'View' and 'JsonView' instances for the view type.
 {-# INLINE renderHtmlOrJson #-}
-renderHtmlOrJson :: forall view. (ViewSupport.View view, ViewSupport.JsonView view, ?context :: ControllerContext, ?request :: Request, ?respond :: Respond) => view -> IO ResponseReceived
+renderHtmlOrJson
+    :: forall view.
+        ( ViewSupport.View view
+        , ViewSupport.JsonView view
+        , Data.Aeson.ToJSON (ViewSupport.JsonResponse view)
+        , Typeable view
+        , ?context :: ControllerContext
+        , ?request :: Request
+        , ?respond :: Respond
+        )
+    => view
+    -> IO ResponseReceived
 renderHtmlOrJson !view = do
+    renderHtmlOrJsonWithStatusCode status200 view
+
+{-# INLINE renderHtmlOrJsonWithStatusCode #-}
+renderHtmlOrJsonWithStatusCode
+    :: forall view.
+        ( ViewSupport.View view
+        , ViewSupport.JsonView view
+        , Data.Aeson.ToJSON (ViewSupport.JsonResponse view)
+        , Typeable view
+        , ?context :: ControllerContext
+        , ?request :: Request
+        , ?respond :: Respond
+        )
+    => Status
+    -> view
+    -> IO ResponseReceived
+renderHtmlOrJsonWithStatusCode status !view = do
     let !currentRequest = ?request
-    let acceptHeader = lookup hAccept (?request.requestHeaders)
-    case acceptHeader of
-        Nothing -> renderHtmlView currentRequest view
-        Just h | "text/html" `isPrefixOf` h -> renderHtmlView currentRequest view
-        _ -> do
-            let accept = fromMaybe "text/html" acceptHeader
-            let send406Error = respondWith $ responseLBS status406 [] "Could not find any acceptable response format"
-            let formats =
-                    [ ("text/html", renderHtmlView currentRequest view)
-                    , ("application/json", renderJson (ViewSupport.json view))
-                    ]
-            fromMaybe send406Error (Accept.mapAcceptMedia formats accept)
+    renderPolymorphic PolymorphicRender
+        { html = Just (renderHtmlViewWithStatus status currentRequest view)
+        , json = Just do
+                let jsonValue = ViewSupport.json view
+                validateOpenApiRenderedView view jsonValue
+                renderJsonWithStatusCode status jsonValue
+        }
 
 renderHtmlView :: (ViewSupport.View view, ?context :: ControllerContext, ?respond :: Respond) => Request -> view -> IO ResponseReceived
-renderHtmlView currentRequest view = do
+renderHtmlView = renderHtmlViewWithStatus status200
+
+renderHtmlViewWithStatus :: (ViewSupport.View view, ?context :: ControllerContext, ?respond :: Respond) => Status -> Request -> view -> IO ResponseReceived
+renderHtmlViewWithStatus status currentRequest view = do
     let next request respond = do
             let ?request = request
             let ?respond = respond
-            (renderHtml view) >>= respondHtml
+            renderHtml view >>= respondHtmlWithStatus status
     consumeFlashMessagesMiddleware next currentRequest ?respond
diff --git a/ihp/IHP/ControllerPrelude.hs b/ihp/IHP/ControllerPrelude.hs
index a72c8dc2d..d8719da6b 100644
--- a/ihp/IHP/ControllerPrelude.hs
+++ b/ihp/IHP/ControllerPrelude.hs
@@ -2,6 +2,7 @@
 module IHP.ControllerPrelude
     ( module IHP.Prelude
     , module IHP.ControllerSupport
+    , module IHP.Controller.ActionDefinition
     , module IHP.Controller.AccessDenied
     , module IHP.Controller.NotFound
     , module IHP.Controller.Render
@@ -29,11 +30,13 @@ module IHP.ControllerPrelude
     , setModal
     , module IHP.Controller.Layout
     , JsonView (..)
+    , json
     , module IHP.Job.Types
     , module IHP.LoginSupport.Helper.Controller
     , Only (..)
     , module IHP.PageHead.ControllerFunctions
     , module IHP.WebSocket
+    , module IHP.OpenApiSupport
     , module IHP.FileStorage.Types
     , module IHP.FileStorage.ControllerFunctions
     , module IHP.FileStorage.Preprocessor.ImageMagick
@@ -43,13 +46,14 @@ module IHP.ControllerPrelude
 import IHP.Prelude
 import IHP.Controller.Param
 import IHP.Controller.FileUpload
-import IHP.Controller.Render
+import IHP.Controller.Render hiding (json)
 import IHP.Controller.AccessDenied
 import IHP.Controller.NotFound
 import IHP.Controller.Session
 import IHP.Controller.BasicAuth
 import IHP.Controller.Cookie
 import IHP.ControllerSupport
+import IHP.Controller.ActionDefinition
 import IHP.ValidationSupport
 import IHP.HaskellSupport
 import IHP.ModelSupport
@@ -69,7 +73,7 @@ import IHP.Controller.Layout
 
 import IHP.Modal.Types
 import qualified IHP.Modal.ControllerFunctions as Modal
-import IHP.ViewSupport (View, JsonView(..))
+import IHP.ViewSupport (View, JsonView(..), json)
 import qualified IHP.ViewSupport as ViewSupport
 
 import IHP.Job.Types
@@ -79,6 +83,7 @@ import IHP.LoginSupport.Helper.Controller
 import IHP.PageHead.ControllerFunctions
 
 import IHP.WebSocket
+import IHP.OpenApiSupport
 
 import IHP.FileStorage.Types
 import IHP.FileStorage.ControllerFunctions
diff --git a/ihp/IHP/ControllerSupport.hs b/ihp/IHP/ControllerSupport.hs
index 6efc6ffb3..7b19436fc 100644
--- a/ihp/IHP/ControllerSupport.hs
+++ b/ihp/IHP/ControllerSupport.hs
@@ -1,7 +1,9 @@
-{-# LANGUAGE TypeSynonymInstances, FlexibleInstances, TypeFamilies, ConstrainedClassMethods, ScopedTypeVariables, FunctionalDependencies, AllowAmbiguousTypes #-}
+{-# LANGUAGE TypeSynonymInstances, FlexibleInstances, TypeFamilies, ConstrainedClassMethods, ScopedTypeVariables, FunctionalDependencies, AllowAmbiguousTypes, RankNTypes, DefaultSignatures, MultiParamTypeClasses, TypeApplications #-}
 
 module IHP.ControllerSupport
 ( Action'
+, ControllerAction'
+, RunControllerAction (..)
 , (|>)
 , getRequestBody
 , getRequestPath
@@ -36,6 +38,7 @@ import Prelude
 import Data.IORef (IORef, modifyIORef', readIORef)
 import Data.ByteString (ByteString)
 import qualified Data.ByteString.Lazy as LBS
+import Data.Kind (Type)
 import Data.Maybe (fromMaybe)
 import Control.Exception.Safe (SomeException, fromException, try, throwIO)
 import qualified Control.Exception as Exception
@@ -71,11 +74,41 @@ import System.IO.Unsafe (unsafePerformIO)
 
 type Action' = IO ResponseReceived
 
+type ControllerAction' controller =
+    ( ?context :: Context.ControllerContext
+    , ?modelContext :: ModelContext
+    , ?theAction :: controller
+    , ?respond :: Respond
+    , ?request :: Request
+    ) =>
+    IO ResponseReceived
+
+-- | Runs a controller's 'ControllerAction' value.
+--
+-- This lets action representations such as 'IHP.Controller.ActionDefinition.ActionDefinition'
+-- plug into the normal controller dispatch without requiring each controller instance to
+-- repeat the same 'runControllerAction' implementation.
+class RunControllerAction controller action where
+    runControllerActionDefault :: (?context :: Context.ControllerContext, ?modelContext :: ModelContext, ?theAction :: controller, ?respond :: Respond, ?request :: Request) => action -> IO ResponseReceived
+
+instance RunControllerAction controller (IO ResponseReceived) where
+    runControllerActionDefault controllerAction = controllerAction
+    {-# INLINABLE runControllerActionDefault #-}
+
 class (Show controller, Eq controller) => Controller controller where
+    type ControllerAction controller :: Type
+    type ControllerAction controller = IO ResponseReceived
+
     beforeAction :: (?context :: Context.ControllerContext, ?modelContext :: ModelContext, ?theAction :: controller, ?respond :: Respond, ?request :: Request) => IO ()
     beforeAction = pure ()
     {-# INLINABLE beforeAction #-}
-    action :: (?context :: Context.ControllerContext, ?modelContext :: ModelContext, ?theAction :: controller, ?respond :: Respond, ?request :: Request) => controller -> IO ResponseReceived
+
+    action :: (?context :: Context.ControllerContext, ?modelContext :: ModelContext, ?theAction :: controller, ?respond :: Respond, ?request :: Request) => controller -> ControllerAction controller
+
+    runControllerAction :: (?context :: Context.ControllerContext, ?modelContext :: ModelContext, ?theAction :: controller, ?respond :: Respond, ?request :: Request) => ControllerAction controller -> IO ResponseReceived
+    default runControllerAction :: (RunControllerAction controller (ControllerAction controller), ?context :: Context.ControllerContext, ?modelContext :: ModelContext, ?theAction :: controller, ?respond :: Respond, ?request :: Request) => ControllerAction controller -> IO ResponseReceived
+    runControllerAction = runControllerActionDefault @controller
+    {-# INLINABLE runControllerAction #-}
 
 class InitControllerContext application where
     initContext :: (?modelContext :: ModelContext, ?request :: Request, ?respond :: Respond, ?context :: Context.ControllerContext) => IO ()
@@ -96,7 +129,7 @@ runAction controller = do
 
     let ?modelContext = authenticatedModelContext
     beforeAction
-    action controller
+    runControllerAction @controller (action controller)
 
 {-# INLINE newContextForAction #-}
 newContextForAction
@@ -251,7 +284,7 @@ jumpToAction :: forall action. (Controller action, ?context :: Context.Controlle
 jumpToAction theAction = do
     let ?theAction = theAction
     beforeAction @action
-    action theAction
+    runControllerAction @action (action theAction)
 
 getRequestBody :: (?request :: Request) => IO LBS.ByteString
 getRequestBody =
diff --git a/ihp/IHP/OpenApiSupport.hs b/ihp/IHP/OpenApiSupport.hs
new file mode 100644
index 000000000..e7a400d3b
--- /dev/null
+++ b/ihp/IHP/OpenApiSupport.hs
@@ -0,0 +1,832 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE FlexibleInstances #-}
+{-# LANGUAGE GADTs #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE UndecidableInstances #-}
+{-# OPTIONS_HADDOCK not-home #-}
+
+module IHP.OpenApiSupport (
+    ToSchema (..),
+    NamedSchema (..),
+    Schema,
+    toSchema,
+    genericDeclareNamedSchema,
+    defaultSchemaOptions,
+    OpenApiGenerationException (..),
+    OpenApiInfo (..),
+    defaultOpenApiInfo,
+    buildOpenApi,
+    buildOpenApiWithInfo,
+    SwaggerUiOptions (..),
+    defaultSwaggerUiOptions,
+    swaggerUi,
+    swaggerUiWithOptions,
+) where
+
+import Control.Exception qualified as Exception
+import Control.Monad.State.Strict qualified as State
+import Data.Aeson qualified as JSON
+import Data.Aeson.Key qualified as JSON.Key
+import Data.Aeson.KeyMap qualified as JSON.KeyMap
+import Data.Attoparsec.ByteString.Char8 (endOfInput, parseOnly, string)
+import Data.ByteString.Char8 qualified as ByteString
+import Data.ByteString.Lazy qualified as LazyByteString
+import Data.Data
+import Data.Map.Strict qualified as Map
+import Data.OpenApi (Definitions, NamedSchema (..), Referenced, Schema, ToSchema (..), declareNamedSchema, declareSchemaRef, defaultSchemaOptions, genericDeclareNamedSchema, toSchema)
+import Data.OpenApi.Declare (runDeclare)
+import Data.Semigroup (Semigroup (..))
+import Data.Text qualified as Text
+import Data.Text.Encoding qualified as Text
+import Data.Typeable qualified as Typeable
+import Data.UUID (nil)
+import Data.UUID qualified as UUID
+import IHP.ModelSupport
+import IHP.OpenApiSupport.ActionDoc
+import IHP.Prelude
+import IHP.Router.Types (UnexpectedMethodException (..))
+import IHP.RouterSupport
+import IHP.ViewSupport (JsonResponse)
+import Network.HTTP.Types.Header (hContentType)
+import Network.HTTP.Types.Method (StdMethod (..), parseMethod, renderStdMethod)
+import Network.HTTP.Types.Status (status200)
+import Network.Wai (Request, Response, defaultRequest, requestMethod, responseBuilder, responseLBS)
+import Text.Blaze.Html.Renderer.Utf8 qualified as Blaze
+import Text.Blaze.Html5 qualified as Html5
+import Text.Blaze.Html5.Attributes qualified as Attr
+
+data OpenApiInfo = OpenApiInfo
+    { openApiTitle :: Text
+    , openApiVersion :: Text
+    , openApiDescription :: Maybe Text
+    }
+    deriving (Eq, Show)
+
+data OpenApiGenerationException = OpenApiGenerationException Text
+    deriving (Eq, Show, Typeable.Typeable)
+
+instance Exception.Exception OpenApiGenerationException
+
+data OpenApiDocument = OpenApiDocument
+    { pathOperations :: PathOperations
+    , componentSchemas :: Definitions Schema
+    }
+
+instance Semigroup OpenApiDocument where
+    left <> right =
+        OpenApiDocument
+            { pathOperations = Map.unionWith Map.union left.pathOperations right.pathOperations
+            , componentSchemas = left.componentSchemas <> right.componentSchemas
+            }
+
+instance Monoid OpenApiDocument where
+    mempty =
+        OpenApiDocument
+            { pathOperations = mempty
+            , componentSchemas = mempty
+            }
+
+defaultOpenApiInfo :: forall application. (Typeable.Typeable application) => OpenApiInfo
+defaultOpenApiInfo =
+    OpenApiInfo
+        { openApiTitle = cs (show (Typeable.typeRep (Proxy @application))) <> " API"
+        , openApiVersion = "1.0.0"
+        , openApiDescription = Nothing
+        }
+
+data SwaggerUiOptions = SwaggerUiOptions
+    { swaggerUiPath :: ByteString
+    , swaggerUiOpenApiPath :: ByteString
+    , swaggerUiInfo :: OpenApiInfo
+    , swaggerUiTitle :: Maybe Text
+    , swaggerUiCssUrl :: Text
+    , swaggerUiBundleJsUrl :: Text
+    , swaggerUiStandalonePresetJsUrl :: Text
+    }
+    deriving (Eq, Show)
+
+{- | Default Swagger UI settings for an application.
+
+This serves the generated OpenAPI JSON at @/api-docs/openapi.json@ and the
+Swagger UI at @/api-docs@.
+-}
+defaultSwaggerUiOptions :: forall application. (Typeable.Typeable application) => SwaggerUiOptions
+defaultSwaggerUiOptions =
+    let info = defaultOpenApiInfo @application
+     in SwaggerUiOptions
+            { swaggerUiPath = "/api-docs"
+            , swaggerUiOpenApiPath = "/openapi.json"
+            , swaggerUiInfo = info
+            , swaggerUiTitle = Nothing
+            , swaggerUiCssUrl = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css"
+            , swaggerUiBundleJsUrl = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js"
+            , swaggerUiStandalonePresetJsUrl = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-standalone-preset.js"
+            }
+
+buildOpenApi :: forall application. (FrontController application, Typeable.Typeable application) => application -> JSON.Value
+buildOpenApi = buildOpenApiWithInfo (defaultOpenApiInfo @application)
+
+buildOpenApiWithInfo :: forall application. (FrontController application) => OpenApiInfo -> application -> JSON.Value
+buildOpenApiWithInfo info application =
+    let ?request = defaultRequest
+        ?respond = dummyRespond
+        ?application = application
+     in let routeTree = RouteCollection (controllers @application |> map routeInspection)
+         in case collectPaths "" routeTree of
+                Left errorMessage -> throwOpenApiGenerationException errorMessage
+                Right OpenApiDocument{pathOperations, componentSchemas} ->
+                    JSON.object
+                        ( [ Just ("openapi" JSON..= ("3.0.3" :: Text))
+                          , Just ("info" JSON..= openApiInfoValue info)
+                          , Just ("paths" JSON..= openApiPathsValue pathOperations)
+                          , if componentSchemas == mempty then Nothing else Just ("components" JSON..= openApiComponentsValue componentSchemas)
+                          ]
+                            |> catMaybes
+                        )
+  where
+    dummyRespond _ = error "buildOpenApi: response callback should never be called"
+
+throwOpenApiGenerationException :: Text -> a
+throwOpenApiGenerationException = Exception.throw . OpenApiGenerationException
+{-# INLINE throwOpenApiGenerationException #-}
+
+{- | Mounts Swagger UI for the current front controller using 'defaultSwaggerUiOptions'.
+
+This adds two undocumented routes:
+
+- the Swagger UI HTML at @/api-docs@
+- the generated OpenAPI document at @/api-docs/openapi.json@
+-}
+swaggerUi ::
+    forall application.
+    ( FrontController application
+    , Typeable.Typeable application
+    , ?application :: application
+    ) =>
+    ControllerRoute application
+swaggerUi = swaggerUiWithOptions (defaultSwaggerUiOptions @application)
+
+{- | Mounts Swagger UI and the generated OpenAPI JSON for the current front controller.
+
+The JSON endpoint is derived from the same mounted router tree via
+'buildOpenApiWithInfo', so the documentation stays aligned with the
+application routing.
+-}
+swaggerUiWithOptions ::
+    forall application.
+    ( FrontController application
+    , ?application :: application
+    ) =>
+    SwaggerUiOptions ->
+    ControllerRoute application
+swaggerUiWithOptions options@SwaggerUiOptions{swaggerUiPath, swaggerUiOpenApiPath, swaggerUiInfo} =
+    let normalizedBasePath = normalizeSwaggerUiBasePath swaggerUiPath
+        normalizedOpenApiPath = normalizeSwaggerUiChildPath swaggerUiOpenApiPath
+        htmlResponse = responseBuilder status200 [(hContentType, "text/html; charset=utf-8")] (Blaze.renderHtmlBuilder (swaggerUiHtml options{swaggerUiPath = normalizedBasePath, swaggerUiOpenApiPath = normalizedOpenApiPath}))
+        application = ?application
+     in withPrefix
+            normalizedBasePath
+            [ getResponseRoute normalizedOpenApiPath (\_ -> responseLBS status200 [(hContentType, "application/json")] (JSON.encode (buildOpenApiWithInfo swaggerUiInfo application)))
+            , getResponseRoute "" (\_ -> htmlResponse)
+            , getResponseRoute "/" (\_ -> htmlResponse)
+            ]
+
+getResponseRoute :: ByteString -> (Request -> Response) -> ControllerRoute application
+getResponseRoute path toResponse = rawRoute do
+    string path
+    pure (\request respond -> handleGet request respond (toResponse request))
+
+handleGet :: Request -> (Response -> IO responseReceived) -> Response -> IO responseReceived
+handleGet request respond response =
+    case parseMethod (requestMethod request) of
+        Right GET -> respond response
+        Right HEAD -> respond response
+        Right method -> Exception.throw UnexpectedMethodException{allowedMethods = [GET, HEAD], method}
+        Left err -> Exception.throwIO (OpenApiGenerationException ("Invalid HTTP method: " <> cs err))
+
+normalizeSwaggerUiBasePath :: ByteString -> ByteString
+normalizeSwaggerUiBasePath path
+    | ByteString.null path = "/api-docs"
+    | ByteString.head path /= '/' = normalizeSwaggerUiBasePath ("/" <> path)
+    | ByteString.length path > 1 && ByteString.last path == '/' = ByteString.init path
+    | otherwise = path
+
+normalizeSwaggerUiChildPath :: ByteString -> ByteString
+normalizeSwaggerUiChildPath path
+    | ByteString.null path = "/openapi.json"
+    | ByteString.head path /= '/' = "/" <> path
+    | otherwise = path
+
+swaggerUiHtml :: SwaggerUiOptions -> Html5.Html
+swaggerUiHtml SwaggerUiOptions{swaggerUiOpenApiPath, swaggerUiInfo, swaggerUiTitle, swaggerUiCssUrl, swaggerUiBundleJsUrl, swaggerUiStandalonePresetJsUrl} =
+    let title = fromMaybe (swaggerUiInfo.openApiTitle <> " Swagger UI") swaggerUiTitle
+        openApiUrlLiteral = jsonStringLiteral (relativeSwaggerUiOpenApiUrl swaggerUiOpenApiPath)
+     in Html5.docTypeHtml do
+            Html5.head do
+                Html5.meta Html5.! Attr.charset "utf-8"
+                Html5.meta Html5.! Attr.name "viewport" Html5.! Attr.content "width=device-width, initial-scale=1"
+                Html5.title (Html5.toHtml title)
+                Html5.link Html5.! Attr.rel "stylesheet" Html5.! Attr.href (Html5.textValue swaggerUiCssUrl)
+                Html5.style "html { box-sizing: border-box; overflow-y: scroll; } *, *:before, *:after { box-sizing: inherit; } body { margin: 0; background: #fafafa; }"
+            Html5.body do
+                Html5.div mempty Html5.! Attr.id "swagger-ui"
+                Html5.script mempty Html5.! Attr.src (Html5.textValue swaggerUiBundleJsUrl)
+                Html5.script mempty Html5.! Attr.src (Html5.textValue swaggerUiStandalonePresetJsUrl)
+                Html5.script (Html5.preEscapedToHtml (swaggerUiBootScript openApiUrlLiteral))
+
+relativeSwaggerUiOpenApiUrl :: ByteString -> Text
+relativeSwaggerUiOpenApiUrl openApiPath =
+    "./" <> Text.dropWhile (== '/') (Text.decodeUtf8 openApiPath)
+
+swaggerUiBootScript :: Text -> Text
+swaggerUiBootScript openApiUrlLiteral =
+    Text.unlines
+        [ "window.onload = function () {"
+        , "  window.ui = SwaggerUIBundle({"
+        , "    url: " <> openApiUrlLiteral <> ","
+        , "    dom_id: '#swagger-ui',"
+        , "    deepLinking: true,"
+        , "    presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],"
+        , "    layout: 'BaseLayout'"
+        , "  });"
+        , "};"
+        ]
+
+jsonStringLiteral :: Text -> Text
+jsonStringLiteral = cs . LazyByteString.toStrict . JSON.encode
+openApiInfoValue :: OpenApiInfo -> JSON.Value
+openApiInfoValue OpenApiInfo{openApiTitle, openApiVersion, openApiDescription} =
+    JSON.object
+        ( [ Just ("title" JSON..= openApiTitle)
+          , Just ("version" JSON..= openApiVersion)
+          , ("description" JSON..=) <$> openApiDescription
+          ]
+            |> catMaybes
+        )
+
+type PathOperations = Map.Map Text (Map.Map Text JSON.Value)
+
+collectPaths :: Text -> RouteInspection -> Either Text OpenApiDocument
+collectPaths currentPrefix = \case
+    RouteLeaf UndocumentedRoute -> Right mempty
+    RouteLeaf (DocumentedRoute documentedRoute) -> collectDocumentedRoute currentPrefix documentedRoute
+    RouteCollection routes -> mconcat <$> mapM (collectPaths currentPrefix) routes
+    RoutePrefix routePrefix routes ->
+        let prefixedPath = appendPathPrefix currentPrefix (Text.decodeUtf8 routePrefix)
+         in mconcat <$> mapM (collectPaths prefixedPath) routes
+
+collectDocumentedRoute :: Text -> DocumentedRouteInfo -> Either Text OpenApiDocument
+collectDocumentedRoute _ (AutoRouteControllerInfo{documentedActions = Nothing}) = Right mempty
+collectDocumentedRoute currentPrefix (AutoRouteControllerInfo{documentedActions = Just docs}) =
+    foldl' (insertActionOperation currentPrefix) (Right mempty) docs
+
+insertActionOperation ::
+    forall controller.
+    ( AutoRoute controller
+    , Data controller
+    , Typeable.Typeable controller
+    ) =>
+    Text ->
+    Either Text OpenApiDocument ->
+    ActionDoc controller ->
+    Either Text OpenApiDocument
+insertActionOperation currentPrefix pathState doc@ActionDoc{actionDocName} = do
+    OpenApiDocument{pathOperations, componentSchemas} <- pathState
+    constructor <- findControllerConstructor @controller actionDocName
+    (actionPath, parameters) <-
+        deriveCustomPathDocumentation @controller currentPrefix constructor
+            >>= \case
+                Just customPathDocumentation -> pure customPathDocumentation
+                Nothing -> do
+                    parameters <- deriveActionParameters @controller constructor
+                    pure (appendPathPrefix currentPrefix (actionPrefixText @controller <> stripActionSuffixText actionDocName), parameters)
+    let (operation, operationSchemas) = actionDocOperationValue doc parameters
+    let methods = allowedMethodsForAction @controller (Text.encodeUtf8 actionDocName)
+    pure
+        OpenApiDocument
+            { pathOperations = foldl' (insertMethod actionPath operation) pathOperations methods
+            , componentSchemas = componentSchemas <> operationSchemas
+            }
+
+findControllerConstructor :: forall controller. (Data controller) => Text -> Either Text Constr
+findControllerConstructor actionName =
+    dataTypeConstrs (dataTypeOf (undefined :: controller))
+        |> find (\constructor -> cs (showConstr constructor) == actionName)
+        |> \case
+            Just constructor -> Right constructor
+            Nothing -> Left ("OpenAPI docs reference unknown action " <> actionName)
+
+insertMethod :: Text -> JSON.Value -> PathOperations -> StdMethod -> PathOperations
+insertMethod actionPath operation paths method = Map.alter updatePath actionPath paths
+  where
+    methodName = httpMethodName method
+    updatePath Nothing = Just (Map.singleton methodName operation)
+    updatePath (Just operations) = Just (Map.insert methodName operation operations)
+
+httpMethodName :: StdMethod -> Text
+httpMethodName = \case
+    GET -> "get"
+    POST -> "post"
+    PUT -> "put"
+    DELETE -> "delete"
+    OPTIONS -> "options"
+    HEAD -> "head"
+    PATCH -> "patch"
+    TRACE -> "trace"
+    CONNECT -> error "OpenAPI does not support CONNECT routes"
+
+appendPathPrefix :: Text -> Text -> Text
+appendPathPrefix currentPrefix nextPrefix =
+    let normalize text
+            | Text.null text = ""
+            | "/" `Text.isPrefixOf` text = text
+            | otherwise = "/" <> text
+        trimTrailingSlash text
+            | Text.length text > 1 && "/" `Text.isSuffixOf` text = Text.dropEnd 1 text
+            | otherwise = text
+        normalizedCurrent = currentPrefix |> normalize |> trimTrailingSlash
+        normalizedNext = normalize nextPrefix
+     in case (normalizedCurrent, normalizedNext) of
+            ("", next) -> next
+            (current, "/") -> current <> "/"
+            (current, next) -> current <> next
+
+openApiPathsValue :: PathOperations -> JSON.Value
+openApiPathsValue paths =
+    paths
+        |> Map.toList
+        |> map
+            ( \(path, operations) ->
+                ( JSON.Key.fromText path
+                , operations
+                    |> Map.toList
+                    |> map (\(method, operation) -> (JSON.Key.fromText method, operation))
+                    |> JSON.KeyMap.fromList
+                    |> JSON.Object
+                )
+            )
+        |> JSON.KeyMap.fromList
+        |> JSON.Object
+
+openApiComponentsValue :: Definitions Schema -> JSON.Value
+openApiComponentsValue schemas =
+    JSON.object
+        [ "schemas" JSON..= schemas
+        ]
+
+actionDocOperationValue :: forall controller. ActionDoc controller -> [QueryParameterDocumentation] -> (JSON.Value, Definitions Schema)
+actionDocOperationValue ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocTags, actionDocOperationId, actionDocView, actionDocRequestBody, actionDocSuccessStatus, actionDocSuccessResponseDescription} parameters =
+    let SchemaDocumentation{documentedSchema, documentedDefinitions} = responseSchemaValue actionDocView
+        parameterDefinitions = parameters |> map (\QueryParameterDocumentation{parameterDefinitions} -> parameterDefinitions) |> mconcat
+        requestBodyDocumentation =
+            actionDocRequestBody
+                |> fmap openApiRequestBodySchemaValue
+        requestBodyDefinitions =
+            requestBodyDocumentation
+                |> fmap (.documentedDefinitions)
+                |> fromMaybe mempty
+        requestBodyValue =
+            case (actionDocRequestBody, requestBodyDocumentation) of
+                (Just requestBodyDoc, Just schemaDocumentation) -> Just ("requestBody" JSON..= openApiRequestBodyValue requestBodyDoc schemaDocumentation.documentedSchema)
+                _ -> Nothing
+     in ( JSON.object
+            ( [ Just ("parameters" JSON..= map queryParameterValue parameters)
+              , Just ("responses" JSON..= JSON.object [cs (show actionDocSuccessStatus) JSON..= successResponseValue actionDocSuccessResponseDescription documentedSchema])
+              , requestBodyValue
+              , ("summary" JSON..=) <$> actionDocSummary
+              , ("description" JSON..=) <$> actionDocDescription
+              , if null actionDocTags then Nothing else Just ("tags" JSON..= actionDocTags)
+              , ("operationId" JSON..=) <$> actionDocOperationId
+              , Just ("x-ihp-action" JSON..= actionDocName)
+              ]
+                |> catMaybes
+            )
+        , documentedDefinitions <> parameterDefinitions <> requestBodyDefinitions
+        )
+
+openApiRequestBodySchemaValue :: OpenApiRequestBodyDoc -> SchemaDocumentation
+openApiRequestBodySchemaValue OpenApiRequestBodyDoc{requestBodySchema} =
+    declareSchemaDocumentation requestBodySchema
+
+openApiRequestBodyValue :: OpenApiRequestBodyDoc -> Referenced Schema -> JSON.Value
+openApiRequestBodyValue OpenApiRequestBodyDoc{requestBodyRequired} schema =
+    JSON.object
+        [ "required" JSON..= requestBodyRequired
+        , "content"
+            JSON..= JSON.object
+                [ "application/json"
+                    JSON..= JSON.object
+                        [ "schema" JSON..= schema
+                        ]
+                ]
+        ]
+
+responseSchemaValue :: forall view. (ToSchema (JsonResponse view)) => Proxy view -> SchemaDocumentation
+responseSchemaValue _ = declareSchemaDocumentation (Proxy @(JsonResponse view))
+
+successResponseValue :: Text -> Referenced Schema -> JSON.Value
+successResponseValue responseDescription schema =
+    JSON.object
+        [ "description" JSON..= responseDescription
+        , "content"
+            JSON..= JSON.object
+                [ "application/json"
+                    JSON..= JSON.object
+                        [ "schema" JSON..= schema
+                        ]
+                ]
+        ]
+
+data ParameterLocation
+    = QueryParameter
+    | PathParameter
+
+data QueryParameterDocumentation = QueryParameterDocumentation
+    { parameterName :: Text
+    , parameterLocation :: ParameterLocation
+    , parameterRequired :: Bool
+    , parameterSchema :: Referenced Schema
+    , parameterDefinitions :: Definitions Schema
+    , parameterExplode :: Maybe Bool
+    }
+
+queryParameterValue :: QueryParameterDocumentation -> JSON.Value
+queryParameterValue QueryParameterDocumentation{parameterName, parameterLocation, parameterRequired, parameterSchema, parameterExplode} =
+    JSON.object
+        ( [ Just ("name" JSON..= parameterName)
+          , Just ("in" JSON..= parameterLocationValue parameterLocation)
+          , Just ("required" JSON..= parameterRequired)
+          , Just ("schema" JSON..= parameterSchema)
+          , if isJust parameterExplode then Just ("style" JSON..= ("form" :: Text)) else Nothing
+          , ("explode" JSON..=) <$> parameterExplode
+          ]
+            |> catMaybes
+        )
+
+parameterLocationValue :: ParameterLocation -> Text
+parameterLocationValue QueryParameter = "query"
+parameterLocationValue PathParameter = "path"
+
+toPathParameter :: QueryParameterDocumentation -> QueryParameterDocumentation
+toPathParameter parameter =
+    parameter
+        { parameterLocation = PathParameter
+        , parameterRequired = True
+        , parameterExplode = Nothing
+        }
+
+data SchemaDocumentation = SchemaDocumentation
+    { documentedSchema :: Referenced Schema
+    , documentedDefinitions :: Definitions Schema
+    }
+
+declareSchemaDocumentation :: forall schema. (ToSchema schema) => Proxy schema -> SchemaDocumentation
+declareSchemaDocumentation proxy =
+    let (definitions, schema) = runDeclare (declareSchemaRef proxy) mempty
+     in SchemaDocumentation
+            { documentedSchema = schema
+            , documentedDefinitions = definitions
+            }
+
+queryParameterDocumentation :: forall field. (Data field) => Text -> Maybe QueryParameterDocumentation
+queryParameterDocumentation parameterName =
+    directParameterDocumentation @field parameterName
+        <|> wrappedIdParameterDocumentation @field parameterName
+
+directParameterDocumentation :: forall field. (Data field) => Text -> Maybe QueryParameterDocumentation
+directParameterDocumentation parameterName =
+    asum
+        [ eqT @field @Text |> fmap (\Refl -> requiredParameter @Text parameterName)
+        , eqT @field @Int |> fmap (\Refl -> requiredParameter @Int parameterName)
+        , eqT @field @Integer |> fmap (\Refl -> requiredParameter @Integer parameterName)
+        , eqT @field @UUID |> fmap (\Refl -> requiredParameter @UUID parameterName)
+        , eqT @field @(Maybe Text) |> fmap (\Refl -> optionalParameter @Text parameterName)
+        , eqT @field @(Maybe Int) |> fmap (\Refl -> optionalParameter @Int parameterName)
+        , eqT @field @(Maybe Integer) |> fmap (\Refl -> optionalParameter @Integer parameterName)
+        , eqT @field @[Text] |> fmap (\Refl -> listParameter @Text parameterName)
+        , eqT @field @[Int] |> fmap (\Refl -> listParameter @Int parameterName)
+        , eqT @field @[Integer] |> fmap (\Refl -> listParameter @Integer parameterName)
+        , eqT @field @[UUID] |> fmap (\Refl -> listParameter @UUID parameterName)
+        ]
+
+requiredParameter :: forall a. (ToSchema a) => Text -> QueryParameterDocumentation
+requiredParameter parameterName =
+    let SchemaDocumentation{documentedSchema, documentedDefinitions} = declareSchemaDocumentation (Proxy @a)
+     in QueryParameterDocumentation
+            { parameterName
+            , parameterLocation = QueryParameter
+            , parameterRequired = True
+            , parameterSchema = documentedSchema
+            , parameterDefinitions = documentedDefinitions
+            , parameterExplode = Nothing
+            }
+
+optionalParameter :: forall a. (ToSchema a) => Text -> QueryParameterDocumentation
+optionalParameter parameterName =
+    let SchemaDocumentation{documentedSchema, documentedDefinitions} = declareSchemaDocumentation (Proxy @a)
+     in QueryParameterDocumentation
+            { parameterName
+            , parameterLocation = QueryParameter
+            , parameterRequired = False
+            , parameterSchema = documentedSchema
+            , parameterDefinitions = documentedDefinitions
+            , parameterExplode = Nothing
+            }
+
+listParameter :: forall a. (ToSchema [a]) => Text -> QueryParameterDocumentation
+listParameter parameterName =
+    let SchemaDocumentation{documentedSchema, documentedDefinitions} = declareSchemaDocumentation (Proxy @[a])
+     in QueryParameterDocumentation
+            { parameterName
+            , parameterLocation = QueryParameter
+            , parameterRequired = False
+            , parameterSchema = documentedSchema
+            , parameterDefinitions = documentedDefinitions
+            , parameterExplode = Just False
+            }
+
+wrappedIdParameterDocumentation :: forall field. (Data field) => Text -> Maybe QueryParameterDocumentation
+wrappedIdParameterDocumentation parameterName
+    | dataTypeName (dataTypeOf (undefined :: field)) /= "IHP.ModelSupport.Types.Id'" = Nothing
+    | otherwise =
+        dataTypeConstrs (dataTypeOf (undefined :: field))
+            |> listToMaybe
+            >>= \constructor -> either (const Nothing) Just (deriveWrappedIdParameter @field constructor parameterName)
+
+deriveWrappedIdParameter :: forall field. (Data field) => Constr -> Text -> Either Text QueryParameterDocumentation
+deriveWrappedIdParameter constructor parameterName =
+    let nextField :: forall inner. (Data inner) => State.StateT (Maybe QueryParameterDocumentation) (Either Text) inner
+        nextField = do
+            parameter <- case queryParameterDocumentation @inner parameterName of
+                Just queryParameter -> pure queryParameter
+                Nothing -> State.lift (Left unsupportedInnerTypeMessage)
+            State.put (Just parameter)
+            case dummyValueForFieldType @inner of
+                Right dummyValue -> pure dummyValue
+                Left errorMessage -> State.lift (Left errorMessage)
+        unsupportedInnerTypeMessage =
+            "OpenAPI does not support the inner primary key type of "
+                <> parameterName
+     in case State.runStateT (fromConstrM nextField constructor :: State.StateT (Maybe QueryParameterDocumentation) (Either Text) field) Nothing of
+            Right (_, Just parameter) -> Right parameter
+            Right (_, Nothing) -> Left ("OpenAPI could not derive the inner primary key type of " <> parameterName)
+            Left errorMessage -> Left errorMessage
+
+dummyValueForFieldType :: forall field. (Data field) => Either Text field
+dummyValueForFieldType =
+    fromMaybe
+        (Left unsupportedDummyTypeMessage)
+        (directDummyValue @field <|> wrappedIdDummyValue @field)
+  where
+    unsupportedDummyTypeMessage =
+        "OpenAPI dummy value is not implemented for type "
+            <> cs (dataTypeName (dataTypeOf (undefined :: field)))
+
+directDummyValue :: forall field. (Data field) => Maybe (Either Text field)
+directDummyValue =
+    asum
+        [ eqT @field @Text |> fmap (\Refl -> Right "")
+        , eqT @field @Int |> fmap (\Refl -> Right 0)
+        , eqT @field @Integer |> fmap (\Refl -> Right 0)
+        , eqT @field @UUID |> fmap (\Refl -> Right nil)
+        , eqT @field @(Maybe Text) |> fmap (\Refl -> Right Nothing)
+        , eqT @field @(Maybe Int) |> fmap (\Refl -> Right Nothing)
+        , eqT @field @(Maybe Integer) |> fmap (\Refl -> Right Nothing)
+        , eqT @field @[Text] |> fmap (\Refl -> Right [])
+        , eqT @field @[Int] |> fmap (\Refl -> Right [])
+        , eqT @field @[Integer] |> fmap (\Refl -> Right [])
+        , eqT @field @[UUID] |> fmap (\Refl -> Right [])
+        ]
+
+wrappedIdDummyValue :: forall field. (Data field) => Maybe (Either Text field)
+wrappedIdDummyValue
+    | dataTypeName (dataTypeOf (undefined :: field)) /= "IHP.ModelSupport.Types.Id'" = Nothing
+    | otherwise =
+        dataTypeConstrs (dataTypeOf (undefined :: field))
+            |> listToMaybe
+            |> fmap deriveWrappedIdDummyValue
+
+deriveWrappedIdDummyValue :: forall field. (Data field) => Constr -> Either Text field
+deriveWrappedIdDummyValue constructor =
+    let nextField :: forall inner. (Data inner) => State.StateT () (Either Text) inner
+        nextField =
+            case dummyValueForFieldType @inner of
+                Right dummyValue -> pure dummyValue
+                Left errorMessage -> State.lift (Left errorMessage)
+     in fst <$> State.runStateT (fromConstrM nextField constructor :: State.StateT () (Either Text) field) ()
+
+buildDummyAction :: forall controller. (Data controller) => Constr -> Either Text controller
+buildDummyAction constructor =
+    let nextField :: forall field. (Data field) => State.StateT () (Either Text) field
+        nextField = State.lift (dummyValueForFieldType @field)
+     in fst <$> State.runStateT (fromConstrM nextField constructor :: State.StateT () (Either Text) controller) ()
+
+data CustomPathFieldMarker = CustomPathFieldMarker
+    { markerFieldName :: Text
+    , markerText :: Text
+    , markerParameter :: QueryParameterDocumentation
+    }
+
+data MarkedAction controller = MarkedAction
+    { markedAction :: controller
+    , markedActionFields :: [CustomPathFieldMarker]
+    }
+
+deriveCustomPathDocumentation :: forall controller. (AutoRoute controller, Data controller) => Text -> Constr -> Either Text (Maybe (Text, [QueryParameterDocumentation]))
+deriveCustomPathDocumentation currentPrefix constructor = do
+    dummyAction <- buildDummyAction @controller constructor
+    case customPathTo dummyAction of
+        Nothing -> pure Nothing
+        Just _ -> do
+            MarkedAction{markedAction, markedActionFields} <- buildMarkedAction @controller constructor
+            customPath <- case customPathTo markedAction of
+                Just path -> pure path
+                Nothing -> Left ("OpenAPI customPathTo returned a path for dummy values but not marker values for action " <> cs (showConstr constructor))
+            validateCustomRouteParser @controller constructor customPath
+            documentCustomPath currentPrefix constructor customPath markedActionFields
+
+buildMarkedAction :: forall controller. (Data controller) => Constr -> Either Text (MarkedAction controller)
+buildMarkedAction constructor =
+    let initialState = (map cs (constrFields constructor), 1, [])
+        nextField :: forall field. (Data field) => State.StateT ([Text], Int, [CustomPathFieldMarker]) (Either Text) field
+        nextField = do
+            (remainingFields, markerIndex, markers) <- State.get
+            case remainingFields of
+                [] -> State.lift (Left ("OpenAPI customPathTo field derivation failed for action " <> cs (showConstr constructor)))
+                (fieldName : restFields) -> do
+                    parameter <- case queryParameterDocumentation @field fieldName of
+                        Just queryParameter -> pure (toPathParameter queryParameter)
+                        Nothing -> State.lift (Left unsupportedTypeMessage)
+                    FieldMarkerValue{fieldMarkerText, fieldMarkerValue} <- State.lift (markerValueForFieldType @field fieldName markerIndex)
+                    State.put
+                        ( restFields
+                        , markerIndex + 1
+                        , markers
+                            <> [ CustomPathFieldMarker
+                                    { markerFieldName = fieldName
+                                    , markerText = fieldMarkerText
+                                    , markerParameter = parameter
+                                    }
+                               ]
+                        )
+                    pure fieldMarkerValue
+                  where
+                    unsupportedTypeMessage =
+                        "OpenAPI customPathTo does not support the field "
+                            <> fieldName
+                            <> " with type "
+                            <> cs (dataTypeName (dataTypeOf (undefined :: field)))
+     in case State.runStateT
+            (fromConstrM nextField constructor :: State.StateT ([Text], Int, [CustomPathFieldMarker]) (Either Text) controller)
+            initialState of
+            Left errorMessage -> Left errorMessage
+            Right (action, ([], _, markers)) -> Right MarkedAction{markedAction = action, markedActionFields = markers}
+            Right (_, (remainingFields, _, _)) ->
+                Left ("OpenAPI customPathTo field derivation did not consume all fields for action " <> cs (showConstr constructor) <> ": " <> cs (show remainingFields) :: Text)
+
+data FieldMarkerValue field = FieldMarkerValue
+    { fieldMarkerText :: Text
+    , fieldMarkerValue :: field
+    }
+
+markerValueForFieldType :: forall field. (Data field) => Text -> Int -> Either Text (FieldMarkerValue field)
+markerValueForFieldType fieldName markerIndex =
+    fromMaybe
+        (Left unsupportedMarkerTypeMessage)
+        (directMarkerValue @field fieldName markerIndex <|> wrappedIdMarkerValue @field fieldName markerIndex)
+  where
+    unsupportedMarkerTypeMessage =
+        "OpenAPI customPathTo marker value is not implemented for type "
+            <> cs (dataTypeName (dataTypeOf (undefined :: field)))
+
+directMarkerValue :: forall field. (Data field) => Text -> Int -> Maybe (Either Text (FieldMarkerValue field))
+directMarkerValue fieldName markerIndex =
+    let textMarker = "__ihp_openapi_" <> fieldName <> "_" <> cs (show markerIndex) <> "__"
+        integerMarker = 900000000 + toInteger markerIndex
+        intMarker :: Int
+        intMarker = fromInteger integerMarker
+        uuidMarkerText = "00000000-0000-0000-0000-" <> Text.justifyRight 12 '0' (cs (show markerIndex))
+        uuidMarker = fromMaybe nil (UUID.fromString (cs uuidMarkerText))
+     in asum
+            [ eqT @field @Text |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = textMarker, fieldMarkerValue = textMarker})
+            , eqT @field @Int |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = cs (show intMarker), fieldMarkerValue = intMarker})
+            , eqT @field @Integer |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = cs (show integerMarker), fieldMarkerValue = integerMarker})
+            , eqT @field @UUID |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = uuidMarkerText, fieldMarkerValue = uuidMarker})
+            , eqT @field @(Maybe Text) |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = textMarker, fieldMarkerValue = Just textMarker})
+            , eqT @field @(Maybe Int) |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = cs (show intMarker), fieldMarkerValue = Just intMarker})
+            , eqT @field @(Maybe Integer) |> fmap (\Refl -> Right FieldMarkerValue{fieldMarkerText = cs (show integerMarker), fieldMarkerValue = Just integerMarker})
+            ]
+
+wrappedIdMarkerValue :: forall field. (Data field) => Text -> Int -> Maybe (Either Text (FieldMarkerValue field))
+wrappedIdMarkerValue fieldName markerIndex
+    | dataTypeName (dataTypeOf (undefined :: field)) /= "IHP.ModelSupport.Types.Id'" = Nothing
+    | otherwise =
+        dataTypeConstrs (dataTypeOf (undefined :: field))
+            |> listToMaybe
+            |> fmap (deriveWrappedIdMarkerValue @field fieldName markerIndex)
+
+deriveWrappedIdMarkerValue :: forall field. (Data field) => Text -> Int -> Constr -> Either Text (FieldMarkerValue field)
+deriveWrappedIdMarkerValue fieldName markerIndex constructor =
+    let nextField :: forall inner. (Data inner) => State.StateT (Maybe Text) (Either Text) inner
+        nextField = do
+            FieldMarkerValue{fieldMarkerText, fieldMarkerValue} <- State.lift (markerValueForFieldType @inner fieldName markerIndex)
+            State.put (Just fieldMarkerText)
+            pure fieldMarkerValue
+     in case State.runStateT (fromConstrM nextField constructor :: State.StateT (Maybe Text) (Either Text) field) Nothing of
+            Right (fieldMarkerValue, Just fieldMarkerText) -> Right FieldMarkerValue{fieldMarkerText, fieldMarkerValue}
+            Right (_, Nothing) -> Left ("OpenAPI customPathTo could not derive the inner primary key marker for " <> fieldName)
+            Left errorMessage -> Left errorMessage
+
+documentCustomPath :: Text -> Constr -> Text -> [CustomPathFieldMarker] -> Either Text (Maybe (Text, [QueryParameterDocumentation]))
+documentCustomPath currentPrefix constructor customPath markers
+    | Text.null customPath = Left ("OpenAPI customPathTo returned an empty path for action " <> actionName)
+    | "?" `Text.isInfixOf` customPath = Left ("OpenAPI customPathTo for action " <> actionName <> " includes a query string. Put all documented route parameters in the path or use AutoRoute.")
+    | otherwise =
+        case filter (\CustomPathFieldMarker{markerText} -> not (markerText `Text.isInfixOf` customPath)) markers of
+            missingMarkers@(_ : _) ->
+                Left
+                    ( "OpenAPI customPathTo for action "
+                        <> actionName
+                        <> " does not include these action fields in the path: "
+                        <> Text.intercalate ", " (map markerFieldName missingMarkers)
+                    )
+            [] ->
+                let openApiPath =
+                        markers
+                            |> foldl'
+                                ( \path CustomPathFieldMarker{markerFieldName, markerText} ->
+                                    Text.replace markerText ("{" <> markerFieldName <> "}") path
+                                )
+                                customPath
+                            |> appendPathPrefix currentPrefix
+                    parameters = map markerParameter markers
+                 in Right (Just (openApiPath, parameters))
+  where
+    actionName = cs (showConstr constructor)
+
+validateCustomRouteParser :: forall controller. (AutoRoute controller, Data controller) => Constr -> Text -> Either Text ()
+validateCustomRouteParser constructor customPath =
+    let actionName = cs (showConstr constructor)
+        method =
+            allowedMethodsForAction @controller (cs actionName)
+                |> listToMaybe
+                |> fromMaybe GET
+        request = defaultRequest{requestMethod = renderStdMethod method}
+        dummyRespond _ = error "validateCustomRouteParser: response callback should never be called"
+        result =
+            let ?request = request
+                ?respond = dummyRespond
+             in parseOnly (customRoutes @controller <* endOfInput) (Text.encodeUtf8 customPath)
+     in case result of
+            Right action
+                | toConstr action == constructor -> Right ()
+                | otherwise ->
+                    Left
+                        ( "OpenAPI customPathTo for action "
+                            <> actionName
+                            <> " is parsed by customRoutes as "
+                            <> cs (showConstr (toConstr action))
+                        )
+            Left parseError ->
+                Left
+                    ( "OpenAPI customPathTo for action "
+                        <> actionName
+                        <> " returned "
+                        <> customPath
+                        <> ", but customRoutes does not parse that path: "
+                        <> cs parseError
+                    )
+
+deriveActionParameters :: forall controller. (Data controller) => Constr -> Either Text [QueryParameterDocumentation]
+deriveActionParameters constr =
+    let initialState = (map cs (constrFields constr), [])
+        nextField :: forall field. (Data field) => State.StateT ([Text], [QueryParameterDocumentation]) (Either Text) field
+        nextField = do
+            (remainingFields, parameters) <- State.get
+            case remainingFields of
+                [] -> State.lift (Left ("OpenAPI field derivation failed for action " <> cs (showConstr constr)))
+                (fieldName : restFields) ->
+                    case queryParameterDocumentation @field fieldName of
+                        Just parameter -> do
+                            State.put (restFields, parameters <> [parameter])
+                            case dummyValueForFieldType @field of
+                                Right dummyValue -> pure dummyValue
+                                Left errorMessage -> State.lift (Left errorMessage)
+                        Nothing -> State.lift (Left unsupportedTypeMessage)
+                  where
+                    unsupportedTypeMessage =
+                        "OpenAPI does not support the AutoRoute field "
+                            <> fieldName
+                            <> " with type "
+                            <> cs (dataTypeName (dataTypeOf (undefined :: field)))
+     in case State.runStateT
+            (fromConstrM nextField constr :: State.StateT ([Text], [QueryParameterDocumentation]) (Either Text) controller)
+            initialState of
+            Left errorMessage -> Left errorMessage
+            Right (_, ([], parameters)) -> Right parameters
+            Right (_, (remainingFields, _)) ->
+                Left ("OpenAPI field derivation did not consume all fields for action " <> cs (showConstr constr) <> ": " <> cs (show remainingFields) :: Text)
+
+instance {-# OVERLAPPABLE #-} (KnownSymbol table, ToSchema (PrimaryKey table)) => ToSchema (Id' table) where
+    declareNamedSchema _ = declareNamedSchema (Proxy @(PrimaryKey table))
diff --git a/ihp/IHP/OpenApiSupport/ActionDoc.hs b/ihp/IHP/OpenApiSupport/ActionDoc.hs
new file mode 100644
index 000000000..39bb354fb
--- /dev/null
+++ b/ihp/IHP/OpenApiSupport/ActionDoc.hs
@@ -0,0 +1,248 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE GADTs #-}
+{-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+
+module IHP.OpenApiSupport.ActionDoc
+    ( ActionDoc (..)
+    , OpenApiRequestBodyDoc (..)
+    , HasOpenApiActionDocs (..)
+    , actionDoc
+    , setOpenApiSummary
+    , setOpenApiDescription
+    , setOpenApiTags
+    , setOpenApiOperationId
+    , setOpenApiRequestBody
+    , setOpenApiRequestBodyRequired
+    , setOpenApiSuccessStatus
+    , setOpenApiSuccessResponseDescription
+    ) where
+
+import Data.Aeson qualified as JSON
+import Data.OpenApi (ToSchema)
+import Data.OpenApi.Schema.Validation qualified as SchemaValidation
+import Data.Proxy (Proxy (..))
+import Data.Text (Text)
+import Data.Typeable qualified as Typeable
+import IHP.ViewSupport qualified as ViewSupport
+import Network.HTTP.Types.Status (Status, status200, statusCode)
+import Prelude
+
+data ActionDoc controller where
+    ActionDoc ::
+        forall controller view.
+        ( ViewSupport.View view
+        , ViewSupport.JsonView view
+        , Typeable.Typeable view
+        , JSON.ToJSON (ViewSupport.JsonResponse view)
+        , ToSchema (ViewSupport.JsonResponse view)
+        ) =>
+        { actionDocName :: Text
+        , actionDocSummary :: Maybe Text
+        , actionDocDescription :: Maybe Text
+        , actionDocTags :: [Text]
+        , actionDocOperationId :: Maybe Text
+        , actionDocView :: Proxy view
+        , actionDocTypedJson :: view -> JSON.Value
+        , actionDocValidateJsonSchema :: view -> Maybe String
+        , actionDocRequestBody :: Maybe OpenApiRequestBodyDoc
+        , actionDocSuccessStatus :: Int
+        , actionDocSuccessResponseDescription :: Text
+        } ->
+        ActionDoc controller
+
+data OpenApiRequestBodyDoc where
+    OpenApiRequestBodyDoc ::
+        forall body.
+        ( ToSchema body
+        , Typeable.Typeable body
+        ) =>
+        { requestBodyRequired :: Bool
+        , requestBodySchema :: Proxy body
+        , requestBodyTypeRep :: Typeable.TypeRep
+        } ->
+        OpenApiRequestBodyDoc
+
+class HasOpenApiActionDocs controller action where
+    openApiActionDocs :: [ActionDoc controller]
+
+actionDoc ::
+    forall view controller.
+    ( ViewSupport.View view
+    , ViewSupport.JsonView view
+    , Typeable.Typeable view
+    , JSON.ToJSON (ViewSupport.JsonResponse view)
+    , ToSchema (ViewSupport.JsonResponse view)
+    ) =>
+    Text -> ActionDoc controller
+actionDoc actionName =
+    ActionDoc
+        { actionDocName = actionName
+        , actionDocSummary = Nothing
+        , actionDocDescription = Nothing
+        , actionDocTags = []
+        , actionDocOperationId = Nothing
+        , actionDocView = Proxy @view
+        , actionDocTypedJson = JSON.toJSON . ViewSupport.jsonTyped
+        , actionDocValidateJsonSchema = SchemaValidation.validatePrettyToJSON . ViewSupport.jsonTyped
+        , actionDocRequestBody = Nothing
+        , actionDocSuccessStatus = statusCode status200
+        , actionDocSuccessResponseDescription = "Successful response"
+        }
+{-# INLINE actionDoc #-}
+
+setOpenApiSummary :: Text -> ActionDoc controller -> ActionDoc controller
+setOpenApiSummary summary ActionDoc{actionDocName, actionDocDescription, actionDocTags, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessStatus, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary = Just summary
+        , actionDocDescription
+        , actionDocTags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription
+        }
+{-# INLINE setOpenApiSummary #-}
+
+setOpenApiDescription :: Text -> ActionDoc controller -> ActionDoc controller
+setOpenApiDescription description ActionDoc{actionDocName, actionDocSummary, actionDocTags, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessStatus, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription = Just description
+        , actionDocTags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription
+        }
+{-# INLINE setOpenApiDescription #-}
+
+setOpenApiTags :: [Text] -> ActionDoc controller -> ActionDoc controller
+setOpenApiTags tags ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessStatus, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription
+        , actionDocTags = tags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription
+        }
+{-# INLINE setOpenApiTags #-}
+
+setOpenApiOperationId :: Text -> ActionDoc controller -> ActionDoc controller
+setOpenApiOperationId operationId ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocTags, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessStatus, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription
+        , actionDocTags
+        , actionDocOperationId = Just operationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription
+        }
+{-# INLINE setOpenApiOperationId #-}
+
+setOpenApiRequestBody ::
+    forall body controller.
+    ( ToSchema body
+    , Typeable.Typeable body
+    ) =>
+    ActionDoc controller ->
+    ActionDoc controller
+setOpenApiRequestBody ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocTags, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocSuccessStatus, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription
+        , actionDocTags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody =
+            Just
+                OpenApiRequestBodyDoc
+                    { requestBodyRequired = True
+                    , requestBodySchema = Proxy @body
+                    , requestBodyTypeRep = Typeable.typeRep (Proxy @body)
+                    }
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription
+        }
+{-# INLINE setOpenApiRequestBody #-}
+
+setOpenApiRequestBodyRequired :: Bool -> ActionDoc controller -> ActionDoc controller
+setOpenApiRequestBodyRequired required ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocTags, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessStatus, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription
+        , actionDocTags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody = setRequired <$> actionDocRequestBody
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription
+        }
+  where
+    setRequired OpenApiRequestBodyDoc{requestBodySchema, requestBodyTypeRep} =
+        OpenApiRequestBodyDoc
+            { requestBodyRequired = required
+            , requestBodySchema
+            , requestBodyTypeRep
+            }
+{-# INLINE setOpenApiRequestBodyRequired #-}
+
+setOpenApiSuccessStatus :: Status -> ActionDoc controller -> ActionDoc controller
+setOpenApiSuccessStatus status ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocTags, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessResponseDescription} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription
+        , actionDocTags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody
+        , actionDocSuccessStatus = statusCode status
+        , actionDocSuccessResponseDescription
+        }
+{-# INLINE setOpenApiSuccessStatus #-}
+
+setOpenApiSuccessResponseDescription :: Text -> ActionDoc controller -> ActionDoc controller
+setOpenApiSuccessResponseDescription description ActionDoc{actionDocName, actionDocSummary, actionDocDescription, actionDocTags, actionDocOperationId, actionDocView, actionDocTypedJson, actionDocValidateJsonSchema, actionDocRequestBody, actionDocSuccessStatus} =
+    ActionDoc
+        { actionDocName
+        , actionDocSummary
+        , actionDocDescription
+        , actionDocTags
+        , actionDocOperationId
+        , actionDocView
+        , actionDocTypedJson
+        , actionDocValidateJsonSchema
+        , actionDocRequestBody
+        , actionDocSuccessStatus
+        , actionDocSuccessResponseDescription = description
+        }
+{-# INLINE setOpenApiSuccessResponseDescription #-}
diff --git a/ihp/IHP/Router/Types.hs b/ihp/IHP/Router/Types.hs
index d9b14d7d2..0e388e6d1 100644
--- a/ihp/IHP/Router/Types.hs
+++ b/ihp/IHP/Router/Types.hs
@@ -9,26 +9,6 @@ import Prelude
 import Data.ByteString (ByteString)
 import Control.Exception (Exception)
 import Network.HTTP.Types.Method
-import qualified Data.HashMap.Strict as HashMap
-import Data.Attoparsec.ByteString.Char8 (Parser)
-import Network.Wai (Application)
-
--- | A controller route entry — either a pre-built HashMap for O(1) dispatch,
--- or a custom Attoparsec parser for dynamic URL patterns.
---
--- 'ControllerRouteMap' carries both an auto-route HashMap and a fallback parser
--- for custom routes. 'ControllerRouteParser' wraps standalone parsers like 'get', 'post',
--- 'webSocketApp', 'startPage', etc.
---
--- 'frontControllerToWAIApp' scans all 'ControllerRouteMap' HashMaps directly (no Attoparsec)
--- for O(1) dispatch, and only falls back to Attoparsec for custom/dynamic route parsers.
-data ControllerRoute application
-    = ControllerRouteMap
-        !(HashMap.HashMap ByteString (application -> Application))
-        (Parser Application)
-        -- ^ Auto-route HashMap + custom routes fallback parser (lazy — only evaluated on HashMap miss)
-    | ControllerRouteParser !(Parser Application)
-        -- ^ Custom route parser (for get, post, webSocketApp, startPage, etc.)
 
 data TypedAutoRouteError
     = BadType
@@ -58,4 +38,4 @@ data UnexpectedMethodException
     { allowedMethods :: [StdMethod]
     , method :: StdMethod
     }
-    deriving (Show, Exception)
\ No newline at end of file
+    deriving (Show, Exception)
diff --git a/ihp/IHP/RouterSupport.hs b/ihp/IHP/RouterSupport.hs
index 42b982be2..5db3458ee 100644
--- a/ihp/IHP/RouterSupport.hs
+++ b/ihp/IHP/RouterSupport.hs
@@ -1,115 +1,140 @@
-{-# LANGUAGE AllowAmbiguousTypes, UndecidableInstances, LambdaCase, ScopedTypeVariables #-}
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE GADTs #-}
+{-# LANGUAGE LambdaCase #-}
+{-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE UndecidableInstances #-}
+
 module IHP.RouterSupport (
-CanRoute (..)
-, HasPath (..)
-, AutoRoute (..)
-, runAction
-, get
-, post
-, startPage
-, frontControllerToWAIApp
-, withPrefix
-, FrontController (..)
-, defaultRouter
-, parseRoute
-, catchAll
-, mountFrontController
-, createAction
-, updateAction
-, urlTo
-, parseUUID
-, parseId
-, parseIntegerId
-, remainingText
-, parseText
-, webSocketApp
-, webSocketAppWithCustomPath
-, webSocketAppWithHTTPFallback
-, onlyAllowMethods
-, getMethod
-, routeParam
-, withImplicits
-, applyConstr
-, ControllerRoute (..)
-, findInRouteMaps
-, buildAutoRouteMap
+    CanRoute (..),
+    HasPath (..),
+    AutoRoute (..),
+    RouteInspection (..),
+    RouteDocumentation (..),
+    DocumentedRouteInfo (..),
+    documentRoute,
+    runAction,
+    get,
+    post,
+    startPage,
+    frontControllerToWAIApp,
+    withPrefix,
+    FrontController (..),
+    defaultRouter,
+    parseRoute,
+    catchAll,
+    mountFrontController,
+    createAction,
+    updateAction,
+    urlTo,
+    actionPrefixText,
+    parseUUID,
+    parseId,
+    parseIntegerId,
+    remainingText,
+    parseText,
+    webSocketApp,
+    webSocketAppWithCustomPath,
+    webSocketAppWithHTTPFallback,
+    onlyAllowMethods,
+    getMethod,
+    routeParam,
+    withImplicits,
+    rawRoute,
+    validateOpenApiRenderedView,
+    applyConstr,
+    ControllerRoute (..),
+    findInRouteMaps,
+    buildAutoRouteMap,
+    stripActionSuffixText,
 ) where
 
-import Prelude hiding (take)
+import Control.Applicative (empty, (<|>))
+import Control.Exception (evaluate)
+import Control.Exception qualified as Exception
+import Control.Exception.Safe (SomeException, catch, throwIO)
+import Control.Monad (join, unless)
+import Control.Monad.State.Strict qualified as State
+import Data.Aeson qualified as JSON
+import Data.Attoparsec.ByteString.Char8 (Parser, choice, endOfInput, parseOnly, string, take, takeByteString, takeTill)
+import Data.Attoparsec.ByteString.Char8 qualified as Attoparsec
 import Data.ByteString (ByteString)
-import Data.Text (Text)
-import Data.Maybe (fromMaybe, mapMaybe)
+import Data.ByteString.Char8 qualified as ByteString
+import Data.Data
+import Data.Dynamic
+import Data.HashMap.Strict qualified as HashMap
+import Data.Kind
 import Data.List (find, isPrefixOf)
-import Control.Monad (unless, join)
-import Control.Applicative ((<|>), empty)
-import Text.Read (readMaybe)
-import Control.Exception.Safe (SomeException, catch, throwIO)
-import Control.Exception (evaluate)
-import qualified IHP.ModelSupport as ModelSupport
-import IHP.FrameworkConfig
+import Data.List qualified as List
+import Data.Maybe (fromMaybe, mapMaybe)
+import Data.String.Conversions (ConvertibleStrings (convertString), cs)
+import Data.TMap qualified as TypeMap
+import Data.Text (Text)
+import Data.Text qualified as Text
+import Data.Text.Encoding qualified as Text
+import Data.Typeable qualified as Typeable
 import Data.UUID
-import Network.HTTP.Types.Method
-import Network.Wai
+import Data.Vault.Lazy qualified as Vault
+import GHC.TypeLits as T
+import IHP.Controller.Context
+import IHP.Controller.Param
 import IHP.ControllerSupport
-import Data.Attoparsec.ByteString.Char8 (string, Parser, parseOnly, take, endOfInput, choice, takeTill, takeByteString)
-import qualified Data.Attoparsec.ByteString.Char8 as Attoparsec
-import GHC.TypeLits
-import Data.Data
-import qualified Control.Monad.State.Strict as State
-import qualified Data.Text as Text
-import Network.HTTP.Types.URI
-import qualified Data.List as List
-import Unsafe.Coerce
+import IHP.ErrorController qualified as ErrorController
+import IHP.FrameworkConfig
 import IHP.HaskellSupport hiding (get)
-import qualified Data.Typeable as Typeable
-import qualified Data.ByteString.Char8 as ByteString
-import Data.String.Conversions (ConvertibleStrings (convertString), cs)
-import qualified Text.Blaze.Html5 as Html5
-import qualified Control.Exception as Exception
-import qualified IHP.ErrorController as ErrorController
-import qualified Network.URI.Encode as URI
-import qualified Data.Text.Encoding as Text
-import Data.Dynamic
+import IHP.ModelSupport qualified as ModelSupport
+import IHP.OpenApiSupport.ActionDoc
 import IHP.Router.Types
 import IHP.Router.UrlGenerator
-import qualified Data.HashMap.Strict as HashMap
 import IHP.WebSocket (WSApp)
-import qualified IHP.WebSocket as WS
-import GHC.TypeLits as T
-import IHP.Controller.Context
-import IHP.Controller.Param
-import Data.Kind
-import qualified Data.TMap as TypeMap
+import IHP.WebSocket qualified as WS
+import Network.HTTP.Types.Header (hContentType)
+import Network.HTTP.Types.Method
+import Network.HTTP.Types.Status (status400, status500)
+import Network.HTTP.Types.URI
+import Network.URI.Encode qualified as URI
+import Network.Wai
 import Network.Wai.Middleware.EarlyReturn (earlyReturnMiddleware)
+import System.IO.Unsafe (unsafePerformIO)
+import Text.Blaze.Html5 qualified as Html5
+import Text.Read (readMaybe)
+import Unsafe.Coerce
+import Prelude hiding (take)
+
+{- | Binds @?request@ and @?respond@ from WAI arguments, then runs the given action.
 
--- | Binds @?request@ and @?respond@ from WAI arguments, then runs the given action.
---
--- This avoids repeating @let ?request = waiRequest; let ?respond = waiRespond@ at each call site.
+This avoids repeating @let ?request = waiRequest; let ?respond = waiRespond@ at each call site.
+-}
 {-# INLINE withImplicits #-}
 withImplicits :: ((?request :: Request, ?respond :: Respond) => Application) -> Application
 withImplicits action waiRequest waiRespond =
     let ?request = waiRequest
         ?respond = waiRespond
-    in action waiRequest waiRespond
-
-runAction'
-    :: forall application controller
-     . ( Controller controller
-       , InitControllerContext application
-       , ?application :: application
-       , Typeable application
-       , Typeable controller
-       )
-     => controller -> Application
+     in action waiRequest waiRespond
+
+runAction' ::
+    forall application controller.
+    ( Controller controller
+    , InitControllerContext application
+    , ?application :: application
+    , Typeable application
+    , Typeable controller
+    ) =>
+    controller -> Application
 runAction' controller waiRequest waiRespond =
-    earlyReturnMiddleware (\request respond -> do
-        context <- setupActionContext @application (Typeable.typeOf controller) request respond
-        let ?context = context
-        let ?respond = respond
-        let ?request = context.request
-        let ?modelContext = ?request.modelContext
-        runAction controller
-        ) waiRequest waiRespond
+    earlyReturnMiddleware
+        ( \request respond -> do
+            context <- setupActionContext @application (Typeable.typeOf controller) request respond
+            let ?context = context
+            let ?respond = respond
+            let ?request = context.request
+            let ?modelContext = ?request.modelContext
+            runAction controller
+        )
+        waiRequest
+        waiRespond
 {-# INLINE runAction' #-}
 
 -- | Catches exceptions from routing and rethrows them wrapped in
@@ -118,20 +143,60 @@ runAction' controller waiRequest waiRespond =
 wrapRouterException :: IO a -> IO a
 wrapRouterException action = action `catch` \(e :: SomeException) -> throwIO (ErrorController.RouterException e)
 
+data DocumentedRouteInfo where
+    AutoRouteControllerInfo ::
+        forall controller.
+        ( AutoRoute controller
+        , Data controller
+        , Typeable.Typeable controller
+        ) =>
+        { documentedActions :: Maybe [ActionDoc controller]
+        } ->
+        DocumentedRouteInfo
+
+data RouteDocumentation
+    = UndocumentedRoute
+    | DocumentedRoute !DocumentedRouteInfo
+
+data RouteInspection
+    = RouteLeaf !RouteDocumentation
+    | RouteCollection [RouteInspection]
+    | RoutePrefix ByteString [RouteInspection]
+
+data ControllerRoute application
+    = ControllerRouteMap
+        { routeMap :: !(HashMap.HashMap ByteString (application -> Application))
+        , routeParser :: !(Parser Application)
+        , routeInspection :: !RouteInspection
+        }
+    | ControllerRouteParser
+        { routeParser :: !(Parser Application)
+        , routeInspection :: !RouteInspection
+        }
+
+rawRoute :: Parser Application -> ControllerRoute application
+rawRoute parser = ControllerRouteParser{routeParser = parser, routeInspection = RouteLeaf UndocumentedRoute}
+{-# INLINE rawRoute #-}
+
+compileControllerRoute :: ControllerRoute application -> Parser Application
+compileControllerRoute ControllerRouteMap{routeParser} = routeParser
+compileControllerRoute ControllerRouteParser{routeParser} = routeParser
+{-# INLINE compileControllerRoute #-}
+
 class FrontController application where
-    controllers
-        :: (?application :: application, ?request :: Request, ?respond :: Respond)
-        => [ControllerRoute application]
+    controllers ::
+        (?application :: application, ?request :: Request, ?respond :: Respond) =>
+        [ControllerRoute application]
 
-    router
-        :: (?application :: application, ?request :: Request, ?respond :: Respond)
-        => [ControllerRoute application] -> Parser Application
+    router ::
+        (?application :: application, ?request :: Request, ?respond :: Respond) =>
+        [ControllerRoute application] -> Parser Application
     router = defaultRouter
-    {-# INLINABLE router #-}
+    {-# INLINEABLE router #-}
 
-defaultRouter
-    :: (?application :: application, ?request :: Request, ?respond :: Respond, FrontController application)
-    => [ControllerRoute application] -> Parser Application
+defaultRouter ::
+    (?application :: application, ?request :: Request, ?respond :: Respond, FrontController application) =>
+    [ControllerRoute application] -> Parser Application
 defaultRouter additionalRoutes = do
     let allRoutes = controllers <> additionalRoutes
         path = rawPathInfo ?request
@@ -142,58 +207,143 @@ defaultRouter additionalRoutes = do
             -- Slow path: fall back to Attoparsec parsers for custom/dynamic routes
             let parsers = concatMap getRouteParsers allRoutes
             choice (map (<* endOfInput) parsers)
-{-# INLINABLE defaultRouter #-}
+{-# INLINEABLE defaultRouter #-}
 
--- | Scan 'ControllerRouteMap' entries for a matching path.
--- Returns as soon as a HashMap contains the path. Skips 'ControllerRouteParser' entries.
+{- | Scan 'ControllerRouteMap' entries for a matching path.
+Returns as soon as a HashMap contains the path. Skips 'ControllerRouteParser' entries.
+-}
 findInRouteMaps :: ByteString -> [ControllerRoute application] -> Maybe (application -> Application)
 findInRouteMaps _ [] = Nothing
-findInRouteMaps path (ControllerRouteMap m _ : rest) =
-    case HashMap.lookup path m of
+findInRouteMaps path (ControllerRouteMap{routeMap} : rest) =
+    case HashMap.lookup path routeMap of
         Just handler -> Just handler
         Nothing -> findInRouteMaps path rest
 findInRouteMaps path (_ : rest) = findInRouteMaps path rest
 
 -- | Extract fallback parsers from controller routes.
 getRouteParsers :: ControllerRoute application -> [Parser Application]
-getRouteParsers (ControllerRouteMap _ fallback) = [fallback]
-getRouteParsers (ControllerRouteParser p) = [p]
-
--- | Returns the url to a given action.
---
--- Uses the baseUrl configured in @Config/Config.hs@. When no @baseUrl@
--- is configured in development mode, it will automatically detect the
--- correct @baseUrl@ value.
---
--- >>> urlTo UsersAction
--- "http://localhost:8000/Users"
---
--- >>> urlTo ShowUserAction { userId = "a32913dd-ef80-4f3e-9a91-7879e17b2ece" }
--- "http://localhost:8000/ShowUser?userId=a32913dd-ef80-4f3e-9a91-7879e17b2ece"
+getRouteParsers ControllerRouteMap{routeParser} = [routeParser]
+getRouteParsers ControllerRouteParser{routeParser} = [routeParser]
+
+data DocumentedRenderExpectation = DocumentedRenderExpectation
+    { expectedViewTypeName :: Text
+    , expectedTypedJson :: Dynamic -> Maybe JSON.Value
+    , expectedJsonSchemaValidationError :: Dynamic -> Maybe String
+    }
+
+openApiRenderExpectationKey :: Vault.Key DocumentedRenderExpectation
+openApiRenderExpectationKey = unsafePerformIO Vault.newKey
+{-# NOINLINE openApiRenderExpectationKey #-}
+
+throwOpenApiRenderMismatch :: (?request :: Request, ?respond :: Respond) => Text -> IO a
+throwOpenApiRenderMismatch message =
+    respondAndExit (responseLBS status500 [(hContentType, "text/plain")] (cs message))
+{-# INLINE throwOpenApiRenderMismatch #-}
+
+validateOpenApiRenderedView
+    :: forall view.
+        ( Typeable.Typeable view
+        , ?request :: Request
+        , ?respond :: Respond
+        )
+    => view
+    -> JSON.Value
+    -> IO ()
+validateOpenApiRenderedView view actualJson =
+    case Vault.lookup openApiRenderExpectationKey ?request.vault of
+        Nothing -> pure ()
+        Just DocumentedRenderExpectation{expectedViewTypeName, expectedTypedJson, expectedJsonSchemaValidationError} ->
+            let renderedViewTypeName = cs (show (Typeable.typeRep (Proxy @view)))
+             in unless
+                    (renderedViewTypeName == expectedViewTypeName)
+                    (throwOpenApiRenderMismatch ("OpenAPI docs expect view " <> cs expectedViewTypeName <> ", but render produced " <> cs renderedViewTypeName))
+                    >> case expectedTypedJson (toDyn view) of
+                        Nothing ->
+                            throwOpenApiRenderMismatch ("OpenAPI docs could not validate the typed JSON for view " <> cs expectedViewTypeName)
+                        Just expectedJson ->
+                            unless
+                                (actualJson == expectedJson)
+                                (throwOpenApiRenderMismatch ("OpenAPI docs expect the JSON generated from jsonTyped of view " <> cs expectedViewTypeName <> ", but render produced a different JSON value"))
+                    >> case expectedJsonSchemaValidationError (toDyn view) of
+                        Nothing -> pure ()
+                        Just validationError ->
+                            throwOpenApiRenderMismatch ("OpenAPI docs schema does not match the JSON generated from jsonTyped of view " <> cs expectedViewTypeName <> ":\n" <> cs validationError)
+{-# INLINE validateOpenApiRenderedView #-}
+
+documentedRenderExpectationForAction :: forall controller. (Data controller) => RouteDocumentation -> controller -> Maybe DocumentedRenderExpectation
+documentedRenderExpectationForAction UndocumentedRoute _ = Nothing
+documentedRenderExpectationForAction (DocumentedRoute (AutoRouteControllerInfo{documentedActions = Nothing})) _ = Nothing
+documentedRenderExpectationForAction (DocumentedRoute (AutoRouteControllerInfo{documentedActions = Just docs})) action =
+    docs
+        |> find (\ActionDoc{actionDocName} -> actionDocName == cs (showConstr (toConstr action)))
+        |> fmap
+            ( \ActionDoc{actionDocView, actionDocTypedJson, actionDocValidateJsonSchema} ->
+                DocumentedRenderExpectation
+                    { expectedViewTypeName = cs (show (Typeable.typeRep actionDocView))
+                    , expectedTypedJson = fmap actionDocTypedJson . fromDynamic
+                    , expectedJsonSchemaValidationError = join . fmap actionDocValidateJsonSchema . fromDynamic
+                    }
+            )
+
+runActionWithRouteDocumentation ::
+    forall application controller.
+    ( Controller controller
+    , InitControllerContext application
+    , ?application :: application
+    , Typeable application
+    , Typeable controller
+    , Data controller
+    ) =>
+    RouteDocumentation ->
+    controller ->
+    Application
+runActionWithRouteDocumentation routeDocumentation action waiRequest waiRespond =
+    let renderExpectation = documentedRenderExpectationForAction routeDocumentation action
+        waiRequest' = case renderExpectation of
+            Just expected -> waiRequest{vault = Vault.insert openApiRenderExpectationKey expected waiRequest.vault}
+            Nothing -> waiRequest
+     in runAction' @application action waiRequest' waiRespond
+{-# INLINE runActionWithRouteDocumentation #-}
+
+{- | Returns the url to a given action.
+
+Uses the baseUrl configured in @Config/Config.hs@. When no @baseUrl@
+is configured in development mode, it will automatically detect the
+correct @baseUrl@ value.
+
+>>> urlTo UsersAction
+"http://localhost:8000/Users"
+
+>>> urlTo ShowUserAction { userId = "a32913dd-ef80-4f3e-9a91-7879e17b2ece" }
+"http://localhost:8000/ShowUser?userId=a32913dd-ef80-4f3e-9a91-7879e17b2ece"
+-}
 urlTo :: (?context :: context, ConfigProvider context, HasPath action) => action -> Text
 urlTo action = ?context.frameworkConfig.baseUrl <> pathTo action
 {-# INLINE urlTo #-}
 
-class HasPath controller => CanRoute controller where
+class (HasPath controller) => CanRoute controller where
     parseRoute' :: (?request :: Request, ?respond :: Respond) => Parser controller
 
-    -- | Builds a WAI Application parser for this controller.
-    --
-    -- The default implementation parses the controller action using 'parseRoute''
-    -- and applies the given callback. The overlappable 'AutoRoute' instance overrides
-    -- this to defer query string parsing and method validation to the Application closure.
+    {- | Builds a WAI Application parser for this controller.
+
+    The default implementation parses the controller action using 'parseRoute''
+    and applies the given callback. The overlappable 'AutoRoute' instance overrides
+    this to defer query string parsing and method validation to the Application closure.
+    -}
     parseRouteWithAction :: (?request :: Request, ?respond :: Respond) => (controller -> Application) -> Parser Application
     parseRouteWithAction toApp = do
         action <- parseRoute'
         pure (toApp action)
     {-# INLINE parseRouteWithAction #-}
 
-    -- | Build a 'ControllerRoute' for this controller.
-    --
-    -- The default wraps the parser in 'ControllerRouteParser'.
-    -- The overlappable 'AutoRoute' instance overrides this to use 'ControllerRouteMap'
-    -- for O(1) HashMap dispatch. This is what 'parseRoute' calls.
-    toControllerRoute :: forall application.
+    {- | Build a 'ControllerRoute' for this controller.
+
+    The default wraps the parser in 'ControllerRouteParser'.
+    The overlappable 'AutoRoute' instance overrides this to use 'ControllerRouteMap'
+    for O(1) HashMap dispatch. This is what 'parseRoute' calls.
+    -}
+    toControllerRoute ::
+        forall application.
         ( ?request :: Request
         , ?respond :: Respond
         , Controller controller
@@ -201,313 +351,324 @@ class HasPath controller => CanRoute controller where
         , ?application :: application
         , Typeable application
         , Typeable controller
-        ) => ControllerRoute application
-    toControllerRoute = ControllerRouteParser (parseRouteWithAction @controller (runAction' @application))
-    {-# INLINABLE toControllerRoute #-}
-
-
--- | Each of these is tried when trying to parse an argument to a controller constructor (i.e. in IHP, an action).
--- The type @d@ is an the type of the argument, and all we know about this type that its conforms to @Data@.
--- We cannot cast @d@ to some arbitrary type, since adding additional constraints to @d@ (such as Read)
--- will break the @fromConstrM@ function which actually constructs the action.
---
--- The approach taken here is to make use of the type equality operator @:~:@
--- to check and see if @d@ happens to be a certain type. If it is,
--- by matching on Just Refl, we are able to use @d@ as the type we matched it to.
---
--- Please consult your doctor before engaging in Haskell type programming.
+        ) =>
+        ControllerRoute application
+    toControllerRoute =
+        ControllerRouteParser
+            { routeParser = parseRouteWithAction @controller (runAction' @application)
+            , routeInspection = RouteLeaf UndocumentedRoute
+            }
+    {-# INLINEABLE toControllerRoute #-}
+
+{- | Each of these is tried when trying to parse an argument to a controller constructor (i.e. in IHP, an action).
+The type @d@ is an the type of the argument, and all we know about this type that its conforms to @Data@.
+We cannot cast @d@ to some arbitrary type, since adding additional constraints to @d@ (such as Read)
+will break the @fromConstrM@ function which actually constructs the action.
+
+The approach taken here is to make use of the type equality operator @:~:@
+to check and see if @d@ happens to be a certain type. If it is,
+by matching on Just Refl, we are able to use @d@ as the type we matched it to.
+
+Please consult your doctor before engaging in Haskell type programming.
+-}
 parseFuncs :: forall d idType. (Data d, Data idType) => (ByteString -> Maybe idType) -> [Maybe ByteString -> Either TypedAutoRouteError d]
-parseFuncs parseIdType = [
-            -- Try and parse @Int@ or @Maybe Int@
-            \case
-                Just queryValue -> case eqT :: Maybe (d :~: Int) of
-                    Just Refl -> case ByteString.readInt queryValue of
-                        Just (n, "") -> Right n
-                        _ -> Left BadType { field = "", value = Just queryValue, expectedType = "Int" }
-                    Nothing -> case eqT :: Maybe (d :~: Maybe Int) of
-                        Just Refl -> Right $ case ByteString.readInt queryValue of
-                            Just (n, "") -> Just n
-                            _ -> Nothing
-                        Nothing -> Left NotMatched
-                Nothing -> case eqT :: Maybe (d :~: Maybe Int) of
-                    Just Refl -> Right Nothing
-                    Nothing -> Left NotMatched,
-
-            \case
-                Just queryValue -> case eqT :: Maybe (d :~: Integer) of
-                    Just Refl -> case ByteString.readInteger queryValue of
-                        Just (n, "") -> Right n
-                        _ -> Left BadType { field = "", value = Just queryValue, expectedType = "Integer" }
-                    Nothing -> case eqT :: Maybe (d :~: Maybe Integer) of
-                        Just Refl -> Right $ case ByteString.readInteger queryValue of
-                            Just (n, "") -> Just n
-                            _ -> Nothing
-                        Nothing -> Left NotMatched
-                Nothing -> case eqT :: Maybe (d :~: Maybe Integer) of
-                    Just Refl -> Right Nothing
-                    Nothing -> Left NotMatched,
-
-            -- Try and parse @Text@ or @Maybe Text@
-            \case
-                Just queryValue -> case eqT :: Maybe (d :~: Text) of
-                    Just Refl -> Right $ cs queryValue
-                    Nothing -> case eqT :: Maybe (d :~: Maybe Text) of
-                        Just Refl -> Right $ Just $ cs queryValue
-                        Nothing -> Left NotMatched
-                Nothing -> case eqT :: Maybe (d :~: Maybe Text) of
-                    Just Refl -> Right Nothing
-                    Nothing -> Left NotMatched,
-            \case
-                Just queryValue -> case parseIdType queryValue of
-                    Just idValue -> case eqT :: Maybe (d :~: idType) of
-                        Just Refl -> Right idValue
-                        Nothing -> Left NotMatched
-                    Nothing -> Left NotMatched
-                Nothing -> Left NotMatched,
-
-            -- Try and parse @[Text]@. If value is not present then default to empty list.
-            \queryValue -> case eqT :: Maybe (d :~: [Text]) of
-                Just Refl -> case queryValue of
-                    Just queryValue -> Right $ Text.splitOn "," (cs queryValue)
-                    Nothing -> Right []
-                Nothing -> Left NotMatched,
-
-            -- Try and parse @[Int]@. If value is not present then default to empty list.
-            \queryValue -> case eqT :: Maybe (d :~: [Int]) of
-                Just Refl -> case queryValue of
-                    Just queryValue -> ByteString.split ',' queryValue
-                        |> mapMaybe (\b -> case ByteString.readInt b of Just (n, "") -> Just n; _ -> Nothing)
-                        |> Right
-                    Nothing -> Right []
-                Nothing -> Left NotMatched,
-
-            \queryValue -> case eqT :: Maybe (d :~: [Integer]) of
-                Just Refl -> case queryValue of
-                    Just queryValue -> ByteString.split ',' queryValue
-                        |> mapMaybe (\b -> case ByteString.readInteger b of Just (n, "") -> Just n; _ -> Nothing)
-                        |> Right
-                    Nothing -> Right []
-                Nothing -> Left NotMatched,
-
-            -- Try and parse a raw [UUID]
-            \queryValue -> case eqT :: Maybe (d :~: [UUID]) of
-                Just Refl -> case queryValue of
-                    Just queryValue -> ByteString.split ',' queryValue
-                        |> mapMaybe fromASCIIBytes
-                        |> Right
-                    Nothing -> Right []
-                Nothing -> Left NotMatched,
-
-            -- Try and parse a raw UUID
-            \queryValue -> case eqT :: Maybe (d :~: UUID) of
-                Just Refl -> case queryValue of
-                    Just queryValue -> queryValue
-                        |> fromASCIIBytes
-                        |> \case
-                            Just uuid -> uuid |> Right
-                            Nothing -> Left BadType { field = "", value = Just queryValue, expectedType = "UUID" }
-                    Nothing -> Left NotMatched
-                Nothing -> Left NotMatched,
-
-            -- This has to be last parser in the list
-            --
-            -- Try and parse a UUID wrapped with a Id. In IHP types these are wrapped in a newtype @Id@ such as @Id User@.
-            -- Since @Id@ is a newtype wrapping a UUID, it has the same data representation in GHC.
-            -- Therefore, we're able to safely cast it to its @Id@ type with @unsafeCoerce@.
-            --
-            -- We cannot use 'eqT' here for checking the types, as it's wrapped inside the @Id@ type. We expect
-            -- that if it looks like a UUID, we can just treat it like an @Id@ type. For that to not overshadow other
-            -- parsers, we need to have this last.
-            \queryValue -> case queryValue of
-                Just queryValue -> queryValue
+parseFuncs parseIdType =
+    [ -- Try and parse @Int@ or @Maybe Int@
+      \case
+        Just queryValue -> case eqT :: Maybe (d :~: Int) of
+            Just Refl -> case ByteString.readInt queryValue of
+                Just (n, "") -> Right n
+                _ -> Left BadType{field = "", value = Just queryValue, expectedType = "Int"}
+            Nothing -> case eqT :: Maybe (d :~: Maybe Int) of
+                Just Refl -> Right $ case ByteString.readInt queryValue of
+                    Just (n, "") -> Just n
+                    _ -> Nothing
+                Nothing -> Left NotMatched
+        Nothing -> case eqT :: Maybe (d :~: Maybe Int) of
+            Just Refl -> Right Nothing
+            Nothing -> Left NotMatched
+    , \case
+        Just queryValue -> case eqT :: Maybe (d :~: Integer) of
+            Just Refl -> case ByteString.readInteger queryValue of
+                Just (n, "") -> Right n
+                _ -> Left BadType{field = "", value = Just queryValue, expectedType = "Integer"}
+            Nothing -> case eqT :: Maybe (d :~: Maybe Integer) of
+                Just Refl -> Right $ case ByteString.readInteger queryValue of
+                    Just (n, "") -> Just n
+                    _ -> Nothing
+                Nothing -> Left NotMatched
+        Nothing -> case eqT :: Maybe (d :~: Maybe Integer) of
+            Just Refl -> Right Nothing
+            Nothing -> Left NotMatched
+    , -- Try and parse @Text@ or @Maybe Text@
+      \case
+        Just queryValue -> case eqT :: Maybe (d :~: Text) of
+            Just Refl -> Right $ cs queryValue
+            Nothing -> case eqT :: Maybe (d :~: Maybe Text) of
+                Just Refl -> Right $ Just $ cs queryValue
+                Nothing -> Left NotMatched
+        Nothing -> case eqT :: Maybe (d :~: Maybe Text) of
+            Just Refl -> Right Nothing
+            Nothing -> Left NotMatched
+    , \case
+        Just queryValue -> case parseIdType queryValue of
+            Just idValue -> case eqT :: Maybe (d :~: idType) of
+                Just Refl -> Right idValue
+                Nothing -> Left NotMatched
+            Nothing -> Left NotMatched
+        Nothing -> Left NotMatched
+    , -- Try and parse @[Text]@. If value is not present then default to empty list.
+      \queryValue -> case eqT :: Maybe (d :~: [Text]) of
+        Just Refl -> case queryValue of
+            Just queryValue -> Right $ Text.splitOn "," (cs queryValue)
+            Nothing -> Right []
+        Nothing -> Left NotMatched
+    , -- Try and parse @[Int]@. If value is not present then default to empty list.
+      \queryValue -> case eqT :: Maybe (d :~: [Int]) of
+        Just Refl -> case queryValue of
+            Just queryValue ->
+                ByteString.split ',' queryValue
+                    |> mapMaybe (\b -> case ByteString.readInt b of Just (n, "") -> Just n; _ -> Nothing)
+                    |> Right
+            Nothing -> Right []
+        Nothing -> Left NotMatched
+    , \queryValue -> case eqT :: Maybe (d :~: [Integer]) of
+        Just Refl -> case queryValue of
+            Just queryValue ->
+                ByteString.split ',' queryValue
+                    |> mapMaybe (\b -> case ByteString.readInteger b of Just (n, "") -> Just n; _ -> Nothing)
+                    |> Right
+            Nothing -> Right []
+        Nothing -> Left NotMatched
+    , -- Try and parse a raw [UUID]
+      \queryValue -> case eqT :: Maybe (d :~: [UUID]) of
+        Just Refl -> case queryValue of
+            Just queryValue ->
+                ByteString.split ',' queryValue
+                    |> mapMaybe fromASCIIBytes
+                    |> Right
+            Nothing -> Right []
+        Nothing -> Left NotMatched
+    , -- Try and parse a raw UUID
+      \queryValue -> case eqT :: Maybe (d :~: UUID) of
+        Just Refl -> case queryValue of
+            Just queryValue ->
+                queryValue
                     |> fromASCIIBytes
                     |> \case
-                        Just uuid -> uuid |> unsafeCoerce |> Right
-                        Nothing -> Left BadType { field = "", value = Just queryValue, expectedType = "UUID" }
-                Nothing -> Left NotMatched
-            ]
+                        Just uuid -> uuid |> Right
+                        Nothing -> Left BadType{field = "", value = Just queryValue, expectedType = "UUID"}
+            Nothing -> Left NotMatched
+        Nothing -> Left NotMatched
+    , -- This has to be last parser in the list
+      --
+      -- Try and parse a UUID wrapped with a Id. In IHP types these are wrapped in a newtype @Id@ such as @Id User@.
+      -- Since @Id@ is a newtype wrapping a UUID, it has the same data representation in GHC.
+      -- Therefore, we're able to safely cast it to its @Id@ type with @unsafeCoerce@.
+      --
+      -- We cannot use 'eqT' here for checking the types, as it's wrapped inside the @Id@ type. We expect
+      -- that if it looks like a UUID, we can just treat it like an @Id@ type. For that to not overshadow other
+      -- parsers, we need to have this last.
+      \queryValue -> case queryValue of
+        Just queryValue ->
+            queryValue
+                |> fromASCIIBytes
+                |> \case
+                    Just uuid -> uuid |> unsafeCoerce |> Right
+                    Nothing -> Left BadType{field = "", value = Just queryValue, expectedType = "UUID"}
+        Nothing -> Left NotMatched
+    ]
 {-# NOINLINE parseFuncs #-}
 
--- | As we fold over a constructor, we want the values parsed from the query string
--- to be in the same order as they are in the constructor.
--- This function uses the field labels from the constructor to sort the values from
--- the query string. As a consequence, constructors with basic record syntax will not work with auto types.
---
--- @data MyController = MyAction Text Int@
---
--- does not work. Instead use,
---
--- @data MyController = MyAction { textArg :: Text, intArg :: Int }@
+{- | As we fold over a constructor, we want the values parsed from the query string
+to be in the same order as they are in the constructor.
+This function uses the field labels from the constructor to sort the values from
+the query string. As a consequence, constructors with basic record syntax will not work with auto types.
+
+@data MyController = MyAction Text Int@
+
+does not work. Instead use,
+
+@data MyController = MyAction { textArg :: Text, intArg :: Int }@
+-}
 querySortedByFields :: Query -> Constr -> Query
-querySortedByFields query constructor = constrFields constructor
+querySortedByFields query constructor =
+    constrFields constructor
         |> map cs
         |> map (\field -> (field, join $ List.lookup field query))
 {-# NOINLINE querySortedByFields #-}
 
--- | Given a constructor and a parsed query string, attempt to construct a value of the constructor's type.
--- For example, given the controller
---
--- @data MyController = MyAction { textArg :: Text, intArg :: Int }@
---
--- this function will receive a representation of the @MyAction@ constructor as well as some query string
--- @[("textArg", "some text"), ("intArg", "123")]@.
---
--- By iterating through the query and attempting to match the type of each constructor argument
--- with some transformation of the query string, we attempt to call @MyAction@.
+{- | Given a constructor and a parsed query string, attempt to construct a value of the constructor's type.
+For example, given the controller
+
+@data MyController = MyAction { textArg :: Text, intArg :: Int }@
+
+this function will receive a representation of the @MyAction@ constructor as well as some query string
+@[("textArg", "some text"), ("intArg", "123")]@.
+
+By iterating through the query and attempting to match the type of each constructor argument
+with some transformation of the query string, we attempt to call @MyAction@.
+-}
 applyConstr :: (Data controller, Data idType) => (ByteString -> Maybe idType) -> Constr -> Query -> Either TypedAutoRouteError controller
-applyConstr parseIdType constructor query = let
-
-    -- | Given some query item (key, optional value), try to parse into the current expected type
-    -- by iterating through the available parse functions.
-    attemptToParseArg :: forall d. (Data d) => (ByteString, Maybe ByteString) -> [Maybe ByteString -> Either TypedAutoRouteError d] -> State.StateT Query (Either TypedAutoRouteError) d
-    attemptToParseArg queryParam@(queryName, queryValue) [] = State.lift (Left NoConstructorMatched
-                { field = queryName
-                , value = queryValue
-                , expectedType = (dataTypeOf (Prelude.undefined :: d)) |> dataTypeName |> cs
-                })
-    attemptToParseArg queryParam@(k, v) (parseFunc:restFuncs) = case parseFunc v of
+applyConstr parseIdType constructor query =
+    let
+        -- \| Given some query item (key, optional value), try to parse into the current expected type
+        -- by iterating through the available parse functions.
+        attemptToParseArg :: forall d. (Data d) => (ByteString, Maybe ByteString) -> [Maybe ByteString -> Either TypedAutoRouteError d] -> State.StateT Query (Either TypedAutoRouteError) d
+        attemptToParseArg queryParam@(queryName, queryValue) [] =
+            State.lift
+                ( Left
+                    NoConstructorMatched
+                        { field = queryName
+                        , value = queryValue
+                        , expectedType = (dataTypeOf (Prelude.undefined :: d)) |> dataTypeName |> cs
+                        }
+                )
+        attemptToParseArg queryParam@(k, v) (parseFunc : restFuncs) = case parseFunc v of
             Right result -> pure result
             -- BadType will be returned if, for example, a text is passed to a query parameter typed as int.
-            Left badType@BadType{} -> State.lift (Left badType { field = k })
+            Left badType@BadType{} -> State.lift (Left badType{field = k})
             -- otherwise, safe to assume the match just failed, so recurse on the rest of the functions and try to find one that matches.
             Left _ -> attemptToParseArg queryParam restFuncs
 
-    -- | Attempt to parse the current expected type, and return its value.
-    -- For the example @MyController@ this is called twice by @fromConstrM@.
-    -- Once, it is called for @textArg@ where @d :: Text@. Then it is called
-    -- for @intArg@ with @d ::: Int@. With both of these values parsed from the query string,
-    -- the controller action is able to be created.
-    nextField :: forall d. (Data d) => State.StateT Query (Either TypedAutoRouteError) d
-    nextField = do
+        -- \| Attempt to parse the current expected type, and return its value.
+        -- For the example @MyController@ this is called twice by @fromConstrM@.
+        -- Once, it is called for @textArg@ where @d :: Text@. Then it is called
+        -- for @intArg@ with @d ::: Int@. With both of these values parsed from the query string,
+        -- the controller action is able to be created.
+        nextField :: forall d. (Data d) => State.StateT Query (Either TypedAutoRouteError) d
+        nextField = do
             queryParams <- State.get
             case queryParams of
                 [] -> State.lift (Left TooFewArguments)
-                (p@(key, value):rest) -> do
+                (p@(key, value) : rest) -> do
                     State.put rest
                     attemptToParseArg p (parseFuncs parseIdType)
-
-
-   in case State.runStateT (fromConstrM nextField constructor) (querySortedByFields query constructor) of
-        Right (x, []) -> pure x
-        Right (_) -> Left TooFewArguments
-        Left e -> Left e  -- runtime type error
+     in
+        case State.runStateT (fromConstrM nextField constructor) (querySortedByFields query constructor) of
+            Right (x, []) -> pure x
+            Right (_) -> Left TooFewArguments
+            Left e -> Left e -- runtime type error
 {-# NOINLINE applyConstr #-}
 
-class Data controller => AutoRoute controller where
+class (Data controller) => AutoRoute controller where
     autoRouteWithIdType :: (?request :: Request, ?respond :: Respond, Data idType) => (ByteString -> Maybe idType) -> Parser controller
     autoRouteWithIdType parseIdFunc =
         let
             query :: Query
             query = queryString ?request
-        in do
-            -- routeMatchParser is a CAF (no ?request dependency), computed once per controller type.
-            -- It handles the static string matching against URL paths.
-            (constr, allowedMethods) <- routeMatchParser @controller
-            action <- case applyConstr parseIdFunc constr query of
+         in
+            do
+                -- routeMatchParser is a CAF (no ?request dependency), computed once per controller type.
+                -- It handles the static string matching against URL paths.
+                (constr, allowedMethods) <- routeMatchParser @controller
+                action <- case applyConstr parseIdFunc constr query of
                     Right parsedAction -> pure parsedAction
                     Left e -> Exception.throw e
-            method <- getMethod
-            unless (allowedMethods |> includes method) (Exception.throw UnexpectedMethodException { allowedMethods, method })
-            pure action
-    {-# INLINABLE autoRouteWithIdType #-}
+                method <- getMethod
+                unless (allowedMethods |> includes method) (Exception.throw UnexpectedMethodException{allowedMethods, method})
+                pure action
+    {-# INLINEABLE autoRouteWithIdType #-}
 
     autoRoute :: (?request :: Request, ?respond :: Respond) => Parser controller
     autoRoute = autoRouteWithIdType (\_ -> Nothing :: Maybe Integer)
-    {-# INLINABLE autoRoute #-}
-
-    -- | Constructs a controller value from a matched constructor and query string.
-    --
-    -- Uses the same id parser as 'autoRoute'. Override this when you override
-    -- 'autoRoute' with 'autoRouteWithIdType' to keep them in sync.
-    --
-    -- This is used by 'parseRoute' to defer query string parsing to the Application
-    -- closure while keeping path matching in the parser.
-    --
-    -- __Example:__
-    --
-    -- > instance AutoRoute MyController where
-    -- >     autoRoute = autoRouteWithIdType (parseIntegerId @(Id MyModel))
-    -- >     applyAction = applyConstr (parseIntegerId @(Id MyModel))
+    {-# INLINEABLE autoRoute #-}
+
+    {- | Constructs a controller value from a matched constructor and query string.
+
+    Uses the same id parser as 'autoRoute'. Override this when you override
+    'autoRoute' with 'autoRouteWithIdType' to keep them in sync.
+
+    This is used by 'parseRoute' to defer query string parsing to the Application
+    closure while keeping path matching in the parser.
+
+    __Example:__
+
+    > instance AutoRoute MyController where
+    >     autoRoute = autoRouteWithIdType (parseIntegerId @(Id MyModel))
+    >     applyAction = applyConstr (parseIntegerId @(Id MyModel))
+    -}
     applyAction :: Constr -> Query -> Either TypedAutoRouteError controller
     applyAction = applyConstr (\_ -> Nothing :: Maybe Integer)
     {-# INLINE applyAction #-}
 
-    -- | Specifies the allowed HTTP methods for a given action
-    --
-    -- The default implementation does a smart guess based on the
-    -- usual naming conventions for controllers.
-    --
-    -- __Example (for default implementation):__
-    --
-    -- >>> allowedMethodsForAction @ProjectsController "DeleteProjectAction"
-    -- [DELETE]
-    --
-    -- >>> allowedMethodsForAction @ProjectsController "UpdateProjectAction"
-    -- [POST, PATCH]
-    --
-    -- >>> allowedMethodsForAction @ProjectsController "CreateProjectAction"
-    -- [POST]
-    --
-    -- >>> allowedMethodsForAction @ProjectsController "ShowProjectAction"
-    -- [GET, HEAD]
-    --
-    -- >>> allowedMethodsForAction @ProjectsController "HelloAction"
-    -- [GET, POST, HEAD]
-    --
+    {- | Specifies the allowed HTTP methods for a given action
+
+    The default implementation does a smart guess based on the
+    usual naming conventions for controllers.
+
+    __Example (for default implementation):__
+
+    >>> allowedMethodsForAction @ProjectsController "DeleteProjectAction"
+    [DELETE]
+
+    >>> allowedMethodsForAction @ProjectsController "UpdateProjectAction"
+    [POST, PATCH]
+
+    >>> allowedMethodsForAction @ProjectsController "CreateProjectAction"
+    [POST]
+
+    >>> allowedMethodsForAction @ProjectsController "ShowProjectAction"
+    [GET, HEAD]
+
+    >>> allowedMethodsForAction @ProjectsController "HelloAction"
+    [GET, POST, HEAD]
+    -}
     allowedMethodsForAction :: ByteString -> [StdMethod]
     allowedMethodsForAction actionName =
-            case actionName of
-                a | "Delete" `ByteString.isPrefixOf` a -> [DELETE]
-                a | "Update" `ByteString.isPrefixOf` a -> [POST, PATCH]
-                a | "Create" `ByteString.isPrefixOf` a -> [POST]
-                a | "Show"   `ByteString.isPrefixOf` a -> [GET, HEAD]
-                _ -> [GET, POST, HEAD]
+        case actionName of
+            a | "Delete" `ByteString.isPrefixOf` a -> [DELETE]
+            a | "Update" `ByteString.isPrefixOf` a -> [POST, PATCH]
+            a | "Create" `ByteString.isPrefixOf` a -> [POST]
+            a | "Show" `ByteString.isPrefixOf` a -> [GET, HEAD]
+            _ -> [GET, POST, HEAD]
     {-# INLINE allowedMethodsForAction #-}
 
-    -- | Custom route parser for overriding individual action routes.
-    --
-    -- Use this to provide custom URL patterns for specific actions while keeping
-    -- the auto-generated routes for all other actions.
-    --
-    -- The custom routes are tried first, before the auto-generated routes.
-    -- The auto-generated route for the overridden action still works as a fallback.
-    --
-    -- __Example:__
-    --
-    -- > instance AutoRoute PostsController where
-    -- >     customRoutes = do
-    -- >         string "/posts/"
-    -- >         postId <- parseId
-    -- >         endOfInput
-    -- >         onlyAllowMethods [GET, HEAD]
-    -- >         pure ShowPostAction { postId }
-    --
+    {- | Custom route parser for overriding individual action routes.
+
+    Use this to provide custom URL patterns for specific actions while keeping
+    the auto-generated routes for all other actions.
+
+    The custom routes are tried first, before the auto-generated routes.
+    The auto-generated route for the overridden action still works as a fallback.
+
+    __Example:__
+
+    > instance AutoRoute PostsController where
+    >     customRoutes = do
+    >         string "/posts/"
+    >         postId <- parseId
+    >         endOfInput
+    >         onlyAllowMethods [GET, HEAD]
+    >         pure ShowPostAction { postId }
+    -}
     customRoutes :: (?request :: Request, ?respond :: Respond) => Parser controller
     customRoutes = empty
     {-# INLINE customRoutes #-}
 
-    -- | Custom path generation for overriding individual action URLs.
-    --
-    -- Use this together with 'customRoutes' to generate custom URLs for specific
-    -- actions while keeping the auto-generated URLs for all other actions.
-    --
-    -- Return @Just path@ for actions with custom URLs, or @Nothing@ to fall back
-    -- to the auto-generated URL.
-    --
-    -- __Example:__
-    --
-    -- > instance AutoRoute PostsController where
-    -- >     customPathTo ShowPostAction { postId } = Just ("/posts/" <> tshow postId)
-    -- >     customPathTo _ = Nothing
-    --
+    {- | Custom path generation for overriding individual action URLs.
+
+    Use this together with 'customRoutes' to generate custom URLs for specific
+    actions while keeping the auto-generated URLs for all other actions.
+
+    Return @Just path@ for actions with custom URLs, or @Nothing@ to fall back
+    to the auto-generated URL.
+
+    __Example:__
+
+    > instance AutoRoute PostsController where
+    >     customPathTo ShowPostAction { postId } = Just ("/posts/" <> tshow postId)
+    >     customPathTo _ = Nothing
+    -}
     customPathTo :: controller -> Maybe Text
     customPathTo _ = Nothing
     {-# INLINE customPathTo #-}
 
--- | Static route-matching parser that becomes a CAF when specialized for a concrete
--- controller type. Uses a 'HashMap' for O(1) action name lookup after matching the prefix.
--- Since it doesn't reference @?request@ or @?respond@, GHC can float this out as a
--- top-level constant.
+{- | Static route-matching parser that becomes a CAF when specialized for a concrete
+controller type. Uses a 'HashMap' for O(1) action name lookup after matching the prefix.
+Since it doesn't reference @?request@ or @?respond@, GHC can float this out as a
+top-level constant.
+-}
 routeMatchParser :: forall controller. (Data controller, AutoRoute controller) => Parser (Constr, [StdMethod])
 routeMatchParser = do
     string prefix
@@ -515,12 +676,13 @@ routeMatchParser = do
     case HashMap.lookup remaining actionMatchMap of
         Just result -> pure result
         Nothing -> fail "no matching action"
-    where
-        prefix :: ByteString
-        prefix = Text.encodeUtf8 (actionPrefixText @controller)
+  where
+    prefix :: ByteString
+    prefix = Text.encodeUtf8 (actionPrefixText @controller)
 
-        actionMatchMap :: HashMap.HashMap ByteString (Constr, [StdMethod])
-        actionMatchMap = HashMap.fromList
+    actionMatchMap :: HashMap.HashMap ByteString (Constr, [StdMethod])
+    actionMatchMap =
+        HashMap.fromList
             [ (actionPath, (constr, allowedMethods))
             | constr <- dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
             , let actionName = ByteString.pack (showConstr constr)
@@ -529,139 +691,165 @@ routeMatchParser = do
             ]
 {-# NOINLINE routeMatchParser #-}
 
--- | Returns the url prefix for a controller. The prefix is based on the
--- module where the controller is defined.
---
--- All controllers defined in the `Web/` directory don't have a prefix at all.
---
--- E.g. controllers in the `Admin/` directory are prefixed with @/admin/@.
-actionPrefixText :: forall (controller :: Type). Typeable controller => Text
+{- | Returns the url prefix for a controller. The prefix is based on the
+module where the controller is defined.
+
+All controllers defined in the `Web/` directory don't have a prefix at all.
+
+E.g. controllers in the `Admin/` directory are prefixed with @/admin/@.
+-}
+actionPrefixText :: forall (controller :: Type). (Typeable controller) => Text
 actionPrefixText
     | "Web." `Text.isPrefixOf` moduleName = "/"
     | "IHP." `Text.isPrefixOf` moduleName = "/"
     | Text.null moduleName = "/"
     | otherwise = "/" <> Text.toLower (getPrefix moduleName) <> "/"
-    where
-        moduleName :: Text
-        moduleName = Text.pack $ Typeable.typeOf (error "unreachable" :: controller)
+  where
+    moduleName :: Text
+    moduleName =
+        Text.pack $
+            Typeable.typeOf (error "unreachable" :: controller)
                 |> Typeable.typeRepTyCon
                 |> Typeable.tyConModule
 
-        getPrefix :: Text -> Text
-        getPrefix t = fst (Text.breakOn "." t)
+    getPrefix :: Text -> Text
+    getPrefix t = fst (Text.breakOn "." t)
 {-# NOINLINE actionPrefixText #-}
 
--- | Strips the "Action" suffix from action names
---
--- >>> stripActionSuffixByteString "ShowUserAction"
--- "ShowUser"
---
--- >>> stripActionSuffixByteString "UsersAction"
--- "UsersAction"
---
--- >>> stripActionSuffixByteString "User"
--- "User"
+{- | Strips the "Action" suffix from action names
+
+>>> stripActionSuffixByteString "ShowUserAction"
+"ShowUser"
+
+>>> stripActionSuffixByteString "UsersAction"
+"UsersAction"
+
+>>> stripActionSuffixByteString "User"
+"User"
+-}
 stripActionSuffixByteString :: ByteString -> ByteString
 stripActionSuffixByteString actionName = fromMaybe actionName (ByteString.stripSuffix "Action" actionName)
 {-# INLINE stripActionSuffixByteString #-}
 
--- | Strips the "Action" suffix from action names
---
--- >>> stripActionSuffixText "ShowUserAction"
--- "ShowUser"
---
--- >>> stripActionSuffixText "UsersAction"
--- "UsersAction"
---
--- >>> stripActionSuffixText "User"
--- "User"
+{- | Strips the "Action" suffix from action names
+
+>>> stripActionSuffixText "ShowUserAction"
+"ShowUser"
+
+>>> stripActionSuffixText "UsersAction"
+"UsersAction"
+
+>>> stripActionSuffixText "User"
+"User"
+-}
 stripActionSuffixText :: Text -> Text
 stripActionSuffixText actionName = fromMaybe actionName (Text.stripSuffix "Action" actionName)
 {-# INLINE stripActionSuffixText #-}
 
-
--- | Returns the create action for a given controller.
--- Example: `createAction @UsersController == Just CreateUserAction`
-createAction :: forall controller. AutoRoute controller => Maybe controller
+{- | Returns the create action for a given controller.
+Example: `createAction @UsersController == Just CreateUserAction`
+-}
+createAction :: forall controller. (AutoRoute controller) => Maybe controller
 createAction = fmap fromConstr createConstructor
-    where
-        createConstructor :: Maybe Constr
-        createConstructor = find isCreateConstructor allConstructors
+  where
+    createConstructor :: Maybe Constr
+    createConstructor = find isCreateConstructor allConstructors
 
-        allConstructors :: [Constr]
-        allConstructors = dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
+    allConstructors :: [Constr]
+    allConstructors = dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
 
-        isCreateConstructor :: Constr -> Bool
-        isCreateConstructor constructor = "Create" `isPrefixOf` showConstr constructor && Prelude.null (constrFields constructor)
+    isCreateConstructor :: Constr -> Bool
+    isCreateConstructor constructor = "Create" `isPrefixOf` showConstr constructor && Prelude.null (constrFields constructor)
 {-# INLINE createAction #-}
 
--- | Returns the update action when given a controller and id.
--- Example: `updateAction @UsersController == Just (\id -> UpdateUserAction id)`
-updateAction :: forall controller id. AutoRoute controller => Maybe (id -> controller)
+{- | Returns the update action when given a controller and id.
+Example: `updateAction @UsersController == Just (\id -> UpdateUserAction id)`
+-}
+updateAction :: forall controller id. (AutoRoute controller) => Maybe (id -> controller)
 updateAction =
-        case updateConstructor of
-            Just constructor -> Just $ \id -> buildInstance constructor id
-            Nothing -> Nothing
-    where
-        updateConstructor :: Maybe Constr
-        updateConstructor = find isUpdateConstructor allConstructors
-
-        buildInstance :: Constr -> id -> controller
-        buildInstance constructor id = State.evalState ((fromConstrM (do
-                i <- State.get
-
-                State.modify (+1)
-                pure (unsafeCoerce id)
-            )) constructor) 0
+    case updateConstructor of
+        Just constructor -> Just $ \id -> buildInstance constructor id
+        Nothing -> Nothing
+  where
+    updateConstructor :: Maybe Constr
+    updateConstructor = find isUpdateConstructor allConstructors
+
+    buildInstance :: Constr -> id -> controller
+    buildInstance constructor id =
+        State.evalState
+            ( ( fromConstrM
+                    ( do
+                        i <- State.get
+
+                        State.modify (+ 1)
+                        pure (unsafeCoerce id)
+                    )
+              )
+                constructor
+            )
+            0
 
-        allConstructors :: [Constr]
-        allConstructors = dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
+    allConstructors :: [Constr]
+    allConstructors = dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
 
-        isUpdateConstructor :: Constr -> Bool
-        isUpdateConstructor constructor = "Update" `isPrefixOf` (showConstr constructor) && (length (constrFields constructor) == 1)
+    isUpdateConstructor :: Constr -> Bool
+    isUpdateConstructor constructor = "Update" `isPrefixOf` (showConstr constructor) && (length (constrFields constructor) == 1)
 {-# INLINE updateAction #-}
 
 instance {-# OVERLAPPABLE #-} (AutoRoute controller, Controller controller) => CanRoute controller where
     parseRoute' = customRoutes <|> autoRoute
-    {-# INLINABLE parseRoute' #-}
+    {-# INLINEABLE parseRoute' #-}
 
-    -- | This is only used as a fallback parser (via lazy thunk in 'ControllerRouteMap').
+    -- \| This is only used as a fallback parser (via lazy thunk in 'ControllerRouteMap').
     -- The primary routing path goes through 'findInRouteMaps' / 'buildAutoRouteMap' instead.
     -- Performance here doesn't matter — keep it simple.
-    parseRouteWithAction toApp = (do
-        action <- customRoutes @controller
-        pure (toApp action)
-      ) <|> (do
-        (constr, allowedMethods) <- routeMatchParser @controller
-        pure $ \waiRequest waiRespond -> wrapRouterException do
-            case applyAction @controller constr (queryString waiRequest) of
-                Left e -> Exception.throw e
-                Right action -> do
-                    case parseMethod (requestMethod waiRequest) of
-                        Right method -> do
-                            unless (allowedMethods |> includes method)
-                                (Exception.throw UnexpectedMethodException { allowedMethods, method })
-                            toApp action waiRequest waiRespond
-                        Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
-      )
-    {-# INLINABLE parseRouteWithAction #-}
-
-    -- | Override to use 'ControllerRouteMap' for O(1) HashMap dispatch.
-    toControllerRoute :: forall application.
-        ( ?request :: Request, ?respond :: Respond, Controller controller
-        , InitControllerContext application, ?application :: application
-        , Typeable application, Typeable controller
-        ) => ControllerRoute application
-    toControllerRoute = ControllerRouteMap
-        (buildAutoRouteMap @controller @application)
-        (parseRouteWithAction @controller (runAction' @application))
-    {-# INLINABLE toControllerRoute #-}
-
--- | Instances of the @QueryParam@ type class can be represented in URLs as query parameters.
--- Currently this is only Int, Text, and both wrapped in List and Maybe.
--- IDs also are representable in a URL, but we are unable to match on polymorphic types using reflection,
--- so we fall back to the default "show" for these.
-class Data a => QueryParam a where
+    parseRouteWithAction toApp =
+        ( do
+            action <- customRoutes @controller
+            pure (toApp action)
+        )
+            <|> ( do
+                    (constr, allowedMethods) <- routeMatchParser @controller
+                    pure $ \waiRequest waiRespond -> wrapRouterException do
+                        case applyAction @controller constr (queryString waiRequest) of
+                            Left e -> Exception.throw e
+                            Right action -> do
+                                case parseMethod (requestMethod waiRequest) of
+                                    Right method -> do
+                                        unless
+                                            (allowedMethods |> includes method)
+                                            (Exception.throw UnexpectedMethodException{allowedMethods, method})
+                                        toApp action waiRequest waiRespond
+                                    Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
+                )
+    {-# INLINEABLE parseRouteWithAction #-}
+
+    -- \| Override to use 'ControllerRouteMap' for O(1) HashMap dispatch.
+    toControllerRoute ::
+        forall application.
+        ( ?request :: Request
+        , ?respond :: Respond
+        , Controller controller
+        , InitControllerContext application
+        , ?application :: application
+        , Typeable application
+        , Typeable controller
+        ) =>
+        ControllerRoute application
+    toControllerRoute =
+        ControllerRouteMap
+            { routeMap = buildAutoRouteMap @controller @application
+            , routeParser = parseRouteWithAction @controller (runAction' @application)
+            , routeInspection = RouteLeaf UndocumentedRoute
+            }
+    {-# INLINEABLE toControllerRoute #-}
+
+{- | Instances of the @QueryParam@ type class can be represented in URLs as query parameters.
+Currently this is only Int, Text, and both wrapped in List and Maybe.
+IDs also are representable in a URL, but we are unable to match on polymorphic types using reflection,
+so we fall back to the default "show" for these.
+-}
+class (Data a) => QueryParam a where
     showQueryParam :: a -> String
 
 instance QueryParam Text where
@@ -676,11 +864,11 @@ instance QueryParam Integer where
 instance QueryParam UUID where
     showQueryParam = show
 
-instance QueryParam a => QueryParam (Maybe a) where
+instance (QueryParam a) => QueryParam (Maybe a) where
     showQueryParam (Just val) = showQueryParam val
     showQueryParam Nothing = ""
 
-instance QueryParam a => QueryParam [a] where
+instance (QueryParam a) => QueryParam [a] where
     showQueryParam = List.intercalate "," . map showQueryParam
 
 instance {-# OVERLAPPABLE #-} (Show controller, AutoRoute controller) => HasPath controller where
@@ -689,40 +877,41 @@ instance {-# OVERLAPPABLE #-} (Show controller, AutoRoute controller) => HasPath
         Nothing ->
             let !ci = constrIndex (toConstr action) - 1
                 (!basePath, !fieldNames) = constrInfoCache !! ci
-            in case fieldNames of
-                [] -> basePath
-                _ ->
-                    let !fieldValues = gmapQ renderFieldForUrl action
-                    in basePath <> buildQueryText fieldNames fieldValues
-        where
-            -- Precomputed per constructor: (basePath, fieldNames).
-            -- Does not reference 'action', so GHC floats this out as a CAF
-            -- when the instance is specialized for a concrete controller type.
-            constrInfoCache :: [(Text, [Text])]
-            constrInfoCache = map mkInfo allConstrs
-                where
-                    allConstrs = dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
-                    !appPrefix = actionPrefixText @controller
-                    mkInfo c =
-                        let !bp = appPrefix <> stripActionSuffixText (Text.pack (showConstr c))
-                            !fns = map Text.pack (constrFields c)
-                        in (bp, fns)
-
-            buildQueryText :: [Text] -> [Text] -> Text
-            buildQueryText names values =
-                zip names values
+             in case fieldNames of
+                    [] -> basePath
+                    _ ->
+                        let !fieldValues = gmapQ renderFieldForUrl action
+                         in basePath <> buildQueryText fieldNames fieldValues
+      where
+        -- Precomputed per constructor: (basePath, fieldNames).
+        -- Does not reference 'action', so GHC floats this out as a CAF
+        -- when the instance is specialized for a concrete controller type.
+        constrInfoCache :: [(Text, [Text])]
+        constrInfoCache = map mkInfo allConstrs
+          where
+            allConstrs = dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
+            !appPrefix = actionPrefixText @controller
+            mkInfo c =
+                let !bp = appPrefix <> stripActionSuffixText (Text.pack (showConstr c))
+                    !fns = map Text.pack (constrFields c)
+                 in (bp, fns)
+
+        buildQueryText :: [Text] -> [Text] -> Text
+        buildQueryText names values =
+            zip names values
                 |> filter (\(_, v) -> not (Text.null v))
                 |> map (\(k, v) -> k <> "=" <> URI.encodeText v)
                 |> Text.intercalate "&"
                 |> (\q -> if Text.null q then q else Text.cons '?' q)
     {-# NOINLINE pathTo #-}
 
--- | Render a controller field value as 'Text' for URL query parameter inclusion.
---
--- Uses type reflection ('eqT') to match known types (Text, UUID, Int, Integer,
--- and their Maybe\/List variants). For newtypes like @Id'@ that wrap a known type,
--- falls back to recursive unwrap via 'gmapQ'.
-renderFieldForUrl :: forall d. Data d => d -> Text
+{- | Render a controller field value as 'Text' for URL query parameter inclusion.
+
+Uses type reflection ('eqT') to match known types (Text, UUID, Int, Integer,
+and their Maybe\/List variants). For newtypes like @Id'@ that wrap a known type,
+falls back to recursive unwrap via 'gmapQ'.
+-}
+renderFieldForUrl :: forall d. (Data d) => d -> Text
 renderFieldForUrl val
     -- UUID first: most common type after Id newtype unwrap
     | Just Refl <- eqT @d @UUID = toText val
@@ -750,183 +939,203 @@ getMethod =
     case parseMethod ?request.requestMethod of
         Left error -> fail (ByteString.unpack error)
         Right method -> pure method
-{-# INLINABLE getMethod #-}
-
--- | Routes a given path to an action when requested via GET.
---
--- __Example:__
---
--- > instance FrontController WebApplication where
--- >     controllers = [
--- >             get "/my-custom-page" NewSessionAction
--- >         ]
---
--- The request @GET \/my-custom-page@ is now executing NewSessionAction
---
--- Also see 'post'.
-get :: (Controller action
+{-# INLINEABLE getMethod #-}
+
+{- | Routes a given path to an action when requested via GET.
+
+__Example:__
+
+> instance FrontController WebApplication where
+>     controllers = [
+>             get "/my-custom-page" NewSessionAction
+>         ]
+
+The request @GET \/my-custom-page@ is now executing NewSessionAction
+
+Also see 'post'.
+-}
+get ::
+    ( Controller action
     , InitControllerContext application
     , ?application :: application
     , Typeable application
     , Typeable action
-    ) => ByteString -> action -> ControllerRoute application
-get path action = ControllerRouteParser $ do
+    ) =>
+    ByteString -> action -> ControllerRoute application
+get path action = rawRoute do
     string path
     pure $ \waiRequest waiRespond ->
         case parseMethod (requestMethod waiRequest) of
             Right GET -> runAction' action waiRequest waiRespond
             Right HEAD -> runAction' action waiRequest waiRespond
-            Right method -> Exception.throw UnexpectedMethodException { allowedMethods = [GET, HEAD], method }
+            Right method -> Exception.throw UnexpectedMethodException{allowedMethods = [GET, HEAD], method}
             Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
-{-# INLINABLE get #-}
-
--- | Routes a given path to an action when requested via POST.
---
--- __Example:__
---
--- > instance FrontController WebApplication where
--- >     controllers = [
--- >             post "/do-something" DoSomethingAction
--- >         ]
---
--- The request @POST \/do-something@ is now executing DoSomethingAction
---
--- Also see 'get'.
-post :: (Controller action
+{-# INLINEABLE get #-}
+
+{- | Routes a given path to an action when requested via POST.
+
+__Example:__
+
+> instance FrontController WebApplication where
+>     controllers = [
+>             post "/do-something" DoSomethingAction
+>         ]
+
+The request @POST \/do-something@ is now executing DoSomethingAction
+
+Also see 'get'.
+-}
+post ::
+    ( Controller action
     , InitControllerContext application
     , ?application :: application
     , Typeable application
     , Typeable action
-    ) => ByteString -> action -> ControllerRoute application
-post path action = ControllerRouteParser $ do
+    ) =>
+    ByteString -> action -> ControllerRoute application
+post path action = rawRoute do
     string path
     pure $ \waiRequest waiRespond ->
         case parseMethod (requestMethod waiRequest) of
             Right POST -> runAction' action waiRequest waiRespond
-            Right method -> Exception.throw UnexpectedMethodException { allowedMethods = [POST], method }
+            Right method -> Exception.throw UnexpectedMethodException{allowedMethods = [POST], method}
             Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
-{-# INLINABLE post #-}
-
--- | Filter methods when writing a custom routing parser
---
--- __Example:__
---
--- > instance CanRoute ApiController where
--- >    parseRoute' = do
--- >        string "/api/"
--- >        let
--- >            createRecordAction = do
--- >                onlyAllowMethods [POST]
--- >
--- >                table <- parseText
--- >                endOfInput
--- >                pure CreateRecordAction { table }
--- >
--- >            updateRecordAction = do
--- >                onlyAllowMethods [PATCH]
--- >
--- >                table <- parseText
--- >                string "/"
--- >                id <- parseUUID
--- >                pure UpdateRecordAction { table, id }
--- >
--- > createRecordAction <|> updateRecordAction
---
+{-# INLINEABLE post #-}
+
+{- | Filter methods when writing a custom routing parser
+
+__Example:__
+
+> instance CanRoute ApiController where
+>    parseRoute' = do
+>        string "/api/"
+>        let
+>            createRecordAction = do
+>                onlyAllowMethods [POST]
+>
+>                table <- parseText
+>                endOfInput
+>                pure CreateRecordAction { table }
+>
+>            updateRecordAction = do
+>                onlyAllowMethods [PATCH]
+>
+>                table <- parseText
+>                string "/"
+>                id <- parseUUID
+>                pure UpdateRecordAction { table, id }
+>
+> createRecordAction <|> updateRecordAction
+-}
 onlyAllowMethods :: (?request :: Request, ?respond :: Respond) => [StdMethod] -> Parser ()
 onlyAllowMethods methods = do
     method <- getMethod
     unless (method `elem` methods) (fail ("Invalid method, expected one of: " <> show methods))
-{-# INLINABLE onlyAllowMethods #-}
-
--- | Routes to a given WebSocket app if the path matches the WebSocket app name
---
--- __Example:__
---
--- > instance FrontController WebApplication where
--- >     controllers = [
--- >             webSocketApp @AutoRefreshWSApp
--- >         ]
---
--- The request @\/AutoRefreshWSApp@ will call the AutoRefreshWSApp
---
-webSocketApp :: forall webSocketApp application.
+{-# INLINEABLE onlyAllowMethods #-}
+
+{- | Routes to a given WebSocket app if the path matches the WebSocket app name
+
+__Example:__
+
+> instance FrontController WebApplication where
+>     controllers = [
+>             webSocketApp @AutoRefreshWSApp
+>         ]
+
+The request @\/AutoRefreshWSApp@ will call the AutoRefreshWSApp
+-}
+webSocketApp ::
+    forall webSocketApp application.
     ( WSApp webSocketApp
     , InitControllerContext application
     , ?application :: application
     , Typeable application
     , Typeable webSocketApp
-    ) => ControllerRoute application
+    ) =>
+    ControllerRoute application
 webSocketApp = webSocketAppWithCustomPath @webSocketApp typeName
-    where
-        typeName :: ByteString
-        typeName = Typeable.typeOf (error "unreachable" :: webSocketApp)
-                |> show
-                |> ByteString.pack
-{-# INLINABLE webSocketApp #-}
-
-webSocketAppWithHTTPFallback :: forall webSocketApp application.
+  where
+    typeName :: ByteString
+    typeName =
+        Typeable.typeOf (error "unreachable" :: webSocketApp)
+            |> show
+            |> ByteString.pack
+{-# INLINEABLE webSocketApp #-}
+
+webSocketAppWithHTTPFallback ::
+    forall webSocketApp application.
     ( WSApp webSocketApp
     , InitControllerContext application
     , ?application :: application
     , Typeable application
     , Typeable webSocketApp
     , Controller webSocketApp
-    ) => ControllerRoute application
+    ) =>
+    ControllerRoute application
 webSocketAppWithHTTPFallback = webSocketAppWithCustomPathAndHTTPFallback @webSocketApp @application typeName
-    where
-        typeName :: ByteString
-        typeName = Typeable.typeOf (error "unreachable" :: webSocketApp)
-                |> show
-                |> ByteString.pack
-{-# INLINABLE webSocketAppWithHTTPFallback #-}
-
--- | Routes to a given WebSocket app if the path matches
---
--- __Example:__
---
--- > instance FrontController WebApplication where
--- >     controllers = [
--- >             webSocketAppWithCustomPath @AutoRefreshWSApp "my-ws-app"
--- >         ]
---
--- The request @\/my-ws-app@ will call the AutoRefreshWSApp
---
-webSocketAppWithCustomPath :: forall webSocketApp application.
+  where
+    typeName :: ByteString
+    typeName =
+        Typeable.typeOf (error "unreachable" :: webSocketApp)
+            |> show
+            |> ByteString.pack
+{-# INLINEABLE webSocketAppWithHTTPFallback #-}
+
+{- | Routes to a given WebSocket app if the path matches
+
+__Example:__
+
+> instance FrontController WebApplication where
+>     controllers = [
+>             webSocketAppWithCustomPath @AutoRefreshWSApp "my-ws-app"
+>         ]
+
+The request @\/my-ws-app@ will call the AutoRefreshWSApp
+-}
+webSocketAppWithCustomPath ::
+    forall webSocketApp application.
     ( WSApp webSocketApp
     , InitControllerContext application
     , ?application :: application
     , Typeable application
     , Typeable webSocketApp
-    ) => ByteString -> ControllerRoute application
-webSocketAppWithCustomPath path = ControllerRouteParser $ do
-        Attoparsec.char '/'
-        string path
-        pure $ withImplicits (startWebSocketAppAndFailOnHTTP @webSocketApp @application (WS.initialState @webSocketApp))
-{-# INLINABLE webSocketAppWithCustomPath #-}
-
-webSocketAppWithCustomPathAndHTTPFallback :: forall webSocketApp application.
+    ) =>
+    ByteString -> ControllerRoute application
+webSocketAppWithCustomPath path = rawRoute do
+    Attoparsec.char '/'
+    string path
+    pure $ withImplicits (startWebSocketAppAndFailOnHTTP @webSocketApp @application (WS.initialState @webSocketApp))
+{-# INLINEABLE webSocketAppWithCustomPath #-}
+
+webSocketAppWithCustomPathAndHTTPFallback ::
+    forall webSocketApp application.
     ( WSApp webSocketApp
     , InitControllerContext application
     , ?application :: application
     , Typeable application
     , Typeable webSocketApp
     , Controller webSocketApp
-    ) => ByteString -> ControllerRoute application
-webSocketAppWithCustomPathAndHTTPFallback path = ControllerRouteParser $ do
-        Attoparsec.char '/'
-        string path
-        let action = WS.initialState @webSocketApp
-        pure $ withImplicits (startWebSocketApp @webSocketApp @application action (runActionWithNewContext action))
-{-# INLINABLE webSocketAppWithCustomPathAndHTTPFallback #-}
-
+    ) =>
+    ByteString -> ControllerRoute application
+webSocketAppWithCustomPathAndHTTPFallback path = rawRoute do
+    Attoparsec.char '/'
+    string path
+    let action = WS.initialState @webSocketApp
+    pure $ withImplicits (startWebSocketApp @webSocketApp @application action (runActionWithNewContext action))
+{-# INLINEABLE webSocketAppWithCustomPathAndHTTPFallback #-}
 
 -- | Defines the start page for a router (when @\/@ is requested).
-startPage :: forall action application. (Controller action, InitControllerContext application, ?application::application, Typeable application, Typeable action) => action -> ControllerRoute application
+startPage :: forall action application. (Controller action, InitControllerContext application, ?application :: application, Typeable application, Typeable action) => action -> ControllerRoute application
 startPage action = get (Text.encodeUtf8 (actionPrefixText @action)) action
-{-# INLINABLE startPage #-}
+{-# INLINEABLE startPage #-}
 
-withPrefix prefix routes = string prefix >> choice (map (\r -> r <* endOfInput) routes)
-{-# INLINABLE withPrefix #-}
+withPrefix :: ByteString -> [ControllerRoute application] -> ControllerRoute application
+withPrefix prefix routes =
+    ControllerRouteParser
+        { routeParser = string prefix >> choice (map (\route -> compileControllerRoute route <* endOfInput) routes)
+        , routeInspection = RoutePrefix prefix (map routeInspection routes)
+        }
+{-# INLINEABLE withPrefix #-}
 
 frontControllerToWAIApp :: forall app (autoRefreshApp :: Type). (FrontController app, WSApp autoRefreshApp, Typeable autoRefreshApp, InitControllerContext ()) => Middleware -> app -> Application -> Application
 frontControllerToWAIApp middleware application notFoundAction waiRequest waiRespond = do
@@ -935,16 +1144,19 @@ frontControllerToWAIApp middleware application notFoundAction waiRequest waiResp
 
     let autoRefreshWSParser :: Parser Application
         autoRefreshWSParser =
-            let ?application = () in
-            let typeName = Typeable.typeOf (error "unreachable" :: autoRefreshApp)
-                    |> show |> ByteString.pack
-            in do
-                Attoparsec.char '/'
-                string typeName
-                pure $ withImplicits (startWebSocketAppAndFailOnHTTP @autoRefreshApp @() (WS.initialState @autoRefreshApp))
-
-    let allRoutes = let ?application = application in
-            ControllerRouteParser autoRefreshWSParser : controllers @app
+            let ?application = ()
+             in let typeName =
+                        Typeable.typeOf (error "unreachable" :: autoRefreshApp)
+                            |> show
+                            |> ByteString.pack
+                 in do
+                        Attoparsec.char '/'
+                        string typeName
+                        pure $ withImplicits (startWebSocketAppAndFailOnHTTP @autoRefreshApp @() (WS.initialState @autoRefreshApp))
+
+    let allRoutes =
+            let ?application = application
+             in ControllerRouteParser{routeParser = autoRefreshWSParser, routeInspection = RouteLeaf UndocumentedRoute} : controllers @app
 
     let path = waiRequest.rawPathInfo
 
@@ -958,31 +1170,50 @@ frontControllerToWAIApp middleware application notFoundAction waiRequest waiResp
             let customParsers = concatMap getRouteParsers allRoutes
 
             routedAction :: Either String Application <-
-                (do
+                ( do
                     res <- evaluate $ parseOnly (choice (map (<* endOfInput) customParsers)) path
                     case res of
                         Left s -> pure $ Left s
                         Right action -> pure $ Right action
-                    )
-                |> wrapRouterException
+                )
+                    |> wrapRouterException
             case routedAction of
                 Left _ -> notFoundAction waiRequest waiRespond
                 Right action -> (middleware action) waiRequest waiRespond
-{-# INLINABLE frontControllerToWAIApp #-}
+{-# INLINEABLE frontControllerToWAIApp #-}
 
 mountFrontController :: forall frontController application. (?request :: Request, ?respond :: Respond, FrontController frontController) => frontController -> ControllerRoute application
-mountFrontController application = ControllerRouteParser (let ?application = application in router [])
-{-# INLINABLE mountFrontController #-}
-
--- | Create a route entry for a controller.
---
--- Automatically uses the HashMap fast path when 'AutoRoute' is available
--- (via the overlappable 'CanRoute' instance), or falls back to Attoparsec
--- for controllers with custom 'CanRoute' instances.
---
--- No user code changes needed — @parseRoute \@PostsController@ picks the
--- optimal strategy at compile time.
-parseRoute :: forall controller application.
+mountFrontController application =
+    let ?application = application
+     in ControllerRouteParser
+            { routeParser = router []
+            , routeInspection = RouteCollection (controllers @frontController |> map routeInspection)
+            }
+{-# INLINEABLE mountFrontController #-}
+
+buildDocumentedRoute ::
+    forall controller application.
+    ( ?request :: Request
+    , ?respond :: Respond
+    , Controller controller
+    , AutoRoute controller
+    , Data controller
+    , InitControllerContext application
+    , ?application :: application
+    , Typeable application
+    , Typeable controller
+    ) =>
+    RouteDocumentation -> ControllerRoute application
+buildDocumentedRoute routeDocumentation =
+    ControllerRouteMap
+        { routeMap = buildAutoRouteMapWithDocumentation @controller @application routeDocumentation
+        , routeParser = parseRouteWithAction @controller (runActionWithRouteDocumentation @application routeDocumentation)
+        , routeInspection = RouteLeaf routeDocumentation
+        }
+{-# INLINEABLE buildDocumentedRoute #-}
+
+parseRoute ::
+    forall controller application.
     ( ?request :: Request
     , ?respond :: Respond
     , CanRoute controller
@@ -991,67 +1222,132 @@ parseRoute :: forall controller application.
     , ?application :: application
     , Typeable application
     , Typeable controller
-    ) => ControllerRoute application
+    ) =>
+    ControllerRoute application
 parseRoute = toControllerRoute @controller @application
-{-# INLINABLE parseRoute #-}
-
--- | Build a HashMap from full paths (prefix + action name) to Application closures.
--- The Application closures take the application value explicitly and handle query string
--- parsing, method validation, and controller execution.
--- Computed once per (controller, application) type pair (NOINLINE CAF).
-buildAutoRouteMap :: forall controller application.
+{-# INLINEABLE parseRoute #-}
+
+{- | Build a HashMap from full paths (prefix + action name) to Application closures.
+The Application closures take the application value explicitly and handle query string
+parsing, method validation, and controller execution.
+Computed once per (controller, application) type pair (NOINLINE CAF).
+-}
+buildAutoRouteMap ::
+    forall controller application.
     ( AutoRoute controller
     , Controller controller
     , InitControllerContext application
     , Typeable application
     , Typeable controller
-    ) => HashMap.HashMap ByteString (application -> Application)
-buildAutoRouteMap = HashMap.fromList
-    [ (prefix <> actionPath, handler)
-    | constr <- dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
-    , let actionName = ByteString.pack (showConstr constr)
-          actionPath = stripActionSuffixByteString actionName
-          allowedMethods = allowedMethodsForAction @controller actionName
-          handler app waiRequest waiRespond =
-              let ?application = app
-              in wrapRouterException do
-                  case parseMethod (requestMethod waiRequest) of
-                      Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
-                      Right method -> do
-                          unless (allowedMethods |> includes method)
-                              (Exception.throw UnexpectedMethodException { allowedMethods, method })
-                          case applyAction @controller constr (queryString waiRequest) of
-                              Left e -> Exception.throw e
-                              Right action -> runAction' @application action waiRequest waiRespond
-    ]
-    where
-        prefix :: ByteString
-        prefix = Text.encodeUtf8 (actionPrefixText @controller)
+    ) =>
+    HashMap.HashMap ByteString (application -> Application)
+buildAutoRouteMap =
+    HashMap.fromList
+        [ (prefix <> actionPath, handler)
+        | constr <- dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
+        , let actionName = ByteString.pack (showConstr constr)
+              actionPath = stripActionSuffixByteString actionName
+              allowedMethods = allowedMethodsForAction @controller actionName
+              handler app waiRequest waiRespond =
+                let ?application = app
+                 in wrapRouterException do
+                        case parseMethod (requestMethod waiRequest) of
+                            Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
+                            Right method -> do
+                                unless
+                                    (allowedMethods |> includes method)
+                                    (Exception.throw UnexpectedMethodException{allowedMethods, method})
+                                case applyAction @controller constr (queryString waiRequest) of
+                                    Left e -> Exception.throw e
+                                    Right action -> runAction' @application action waiRequest waiRespond
+        ]
+  where
+    prefix :: ByteString
+    prefix = Text.encodeUtf8 (actionPrefixText @controller)
 {-# NOINLINE buildAutoRouteMap #-}
 
-parseUUIDOrTextId ::  ByteString -> Maybe Dynamic
-parseUUIDOrTextId queryVal = queryVal
-    |> fromASCIIBytes
-    |> \case
-        Just uuid -> uuid |> toDyn |> Just
-        Nothing -> Nothing
+buildAutoRouteMapWithDocumentation ::
+    forall controller application.
+    ( AutoRoute controller
+    , Controller controller
+    , Data controller
+    , InitControllerContext application
+    , Typeable application
+    , Typeable controller
+    ) =>
+    RouteDocumentation -> HashMap.HashMap ByteString (application -> Application)
+buildAutoRouteMapWithDocumentation routeDocumentation =
+    HashMap.fromList
+        [ (prefix <> actionPath, handler)
+        | constr <- dataTypeConstrs (dataTypeOf (Prelude.undefined :: controller))
+        , let actionName = ByteString.pack (showConstr constr)
+              actionPath = stripActionSuffixByteString actionName
+              allowedMethods = allowedMethodsForAction @controller actionName
+              handler app waiRequest waiRespond =
+                let ?application = app
+                 in case parseMethod (requestMethod waiRequest) of
+                        Left err -> error ("Invalid HTTP method: " <> ByteString.unpack err)
+                        Right method -> do
+                            unless
+                                (allowedMethods |> includes method)
+                                (Exception.throw UnexpectedMethodException{allowedMethods, method})
+                            case applyAction @controller constr (queryString waiRequest) of
+                                Left e -> waiRespond $ responseLBS status400 [(hContentType, "text/plain")] (cs $ show e)
+                                Right action -> runActionWithRouteDocumentation @application routeDocumentation action waiRequest waiRespond
+        ]
+  where
+    prefix :: ByteString
+    prefix = Text.encodeUtf8 (actionPrefixText @controller)
+{-# NOINLINE buildAutoRouteMapWithDocumentation #-}
+
+documentRoute ::
+    forall controller application.
+    ( ?request :: Request
+    , ?respond :: Respond
+    , Controller controller
+    , AutoRoute controller
+    , HasOpenApiActionDocs controller (ControllerAction controller)
+    , Data controller
+    , InitControllerContext application
+    , ?application :: application
+    , Typeable application
+    , Typeable controller
+    ) =>
+    ControllerRoute application
+documentRoute =
+    buildDocumentedRoute @controller @application
+        ( DocumentedRoute
+            ( AutoRouteControllerInfo
+                { documentedActions = Just (openApiActionDocs @controller @(ControllerAction controller))
+                }
+            )
+        )
+{-# INLINEABLE documentRoute #-}
+
+parseUUIDOrTextId :: ByteString -> Maybe Dynamic
+parseUUIDOrTextId queryVal =
+    queryVal
+        |> fromASCIIBytes
+        |> \case
+            Just uuid -> uuid |> toDyn |> Just
+            Nothing -> Nothing
 
-parseRouteWithId
-    :: forall controller application.
-        (
-            ?request :: Request,
-            ?respond :: Respond,
-            CanRoute controller,
-            Controller controller,
-            InitControllerContext application,
-            ?application :: application,
-            Typeable application,
-            Typeable controller)
-        => ControllerRoute application
+parseRouteWithId ::
+    forall controller application.
+    ( ?request :: Request
+    , ?respond :: Respond
+    , CanRoute controller
+    , Controller controller
+    , InitControllerContext application
+    , ?application :: application
+    , Typeable application
+    , Typeable controller
+    ) =>
+    ControllerRoute application
 parseRouteWithId = parseRoute @controller @application
 
 catchAll :: forall action application. (Controller action, InitControllerContext application, Typeable action, ?application :: application, Typeable application, Data action) => action -> ControllerRoute application
-catchAll action = ControllerRouteParser $ do
+catchAll action = rawRoute do
     string (Text.encodeUtf8 (actionPrefixText @action))
     _ <- takeByteString
     pure (runAction' @application action)
@@ -1065,63 +1361,65 @@ instance {-# OVERLAPPABLE #-} (HasPath action) => ConvertibleStrings action Html
 -- | Parses and returns an UUID
 parseUUID :: Parser UUID
 parseUUID = do
-        uuid <- take 36
-        case fromASCIIBytes uuid of
-            Just theUUID -> pure theUUID
-            Nothing -> fail "not uuid"
-{-# INLINABLE parseUUID #-}
+    uuid <- take 36
+    case fromASCIIBytes uuid of
+        Just theUUID -> pure theUUID
+        Nothing -> fail "not uuid"
+{-# INLINEABLE parseUUID #-}
 
 -- | Parses an UUID, afterwards wraps it in an Id
 parseId :: ((ModelSupport.PrimaryKey table) ~ UUID) => Parser (ModelSupport.Id' table)
 parseId = ModelSupport.Id <$> parseUUID
-{-# INLINABLE parseId #-}
+{-# INLINEABLE parseId #-}
 
 -- | Returns all the remaining text until the end of the input
 remainingText :: Parser Text
 remainingText = Text.decodeUtf8 <$> takeByteString
-{-# INLINABLE remainingText #-}
+{-# INLINEABLE remainingText #-}
 
 -- | Parses until the next @/@
 parseText :: Parser Text
 parseText = Text.decodeUtf8 <$> takeTill ('/' ==)
-{-# INLINABLE parseText #-}
+{-# INLINEABLE parseText #-}
 
 parseIntegerId :: (Data idType) => ByteString -> Maybe idType
-parseIntegerId queryVal = let
-    rawValue :: Maybe Integer = readMaybe (cs queryVal :: String)
-    in
-       rawValue >>= Just . unsafeCoerce
-
--- | Parses and returns an integer
--- parseRational :: (Integral a) => Parser a
--- parseRational = Attoparsec.decimal
-
--- | Parses a route query parameter
---
--- __Example:__
---
--- > let showPost = do
--- >     string "/post"
--- >     let postId = routeParam "postId"
--- >     pure ShowPostAction { .. }
--- Will parse the `postId` query in `/post?postId=09b545dd-9744-4ef8-87b8-8d227f4faa1e`
---
+parseIntegerId queryVal =
+    let
+        rawValue :: Maybe Integer = readMaybe (cs queryVal :: String)
+     in
+        rawValue >>= Just . unsafeCoerce
+
+{- | Parses and returns an integer
+parseRational :: (Integral a) => Parser a
+parseRational = Attoparsec.decimal
+-}
+
+{- | Parses a route query parameter
+
+__Example:__
+
+> let showPost = do
+>     string "/post"
+>     let postId = routeParam "postId"
+>     pure ShowPostAction { .. }
+Will parse the `postId` query in `/post?postId=09b545dd-9744-4ef8-87b8-8d227f4faa1e`
+-}
 routeParam :: (?request :: Request, ?respond :: Respond, ParamReader paramType) => ByteString -> paramType
 routeParam paramName =
     let customFields = TypeMap.insert ?request TypeMap.empty
-    in
-        let ?context = FrozenControllerContext { customFields }
-        in param paramName
-
--- | Display a better error when the user missed to pass an argument to an action.
---
--- E.g. when you forgot to pass a projectId to the ShowProjectAction:
---
--- > <a href={ShowProjectAction}>Show project</a>
---
--- The correct code would be this:
---
--- > <a href={ShowProjectAction projectId}>Show project</a>
---
--- See https://github.com/digitallyinduced/ihp/issues/840
-instance ((T.TypeError (T.Text "Looks like you forgot to pass a " :<>: (T.ShowType argument) :<>: T.Text " to this " :<>: (T.ShowType controller))), Data argument, Data controller, Data (argument -> controller)) => AutoRoute (argument -> controller) where
+     in let ?context = FrozenControllerContext{customFields}
+         in param paramName
+
+{- | Display a better error when the user missed to pass an argument to an action.
+
+E.g. when you forgot to pass a projectId to the ShowProjectAction:
+
+> <a href={ShowProjectAction}>Show project</a>
+
+The correct code would be this:
+
+> <a href={ShowProjectAction projectId}>Show project</a>
+
+See https://github.com/digitallyinduced/ihp/issues/840
+-}
+instance ((T.TypeError (T.Text "Looks like you forgot to pass a " :<>: (T.ShowType argument) :<>: T.Text " to this " :<>: (T.ShowType controller))), Data argument, Data controller, Data (argument -> controller)) => AutoRoute (argument -> controller)
diff --git a/ihp/IHP/ViewPrelude.hs b/ihp/IHP/ViewPrelude.hs
index 36f599e0a..5a040978d 100644
--- a/ihp/IHP/ViewPrelude.hs
+++ b/ihp/IHP/ViewPrelude.hs
@@ -23,6 +23,7 @@ module IHP.ViewPrelude (
     module IHP.ViewSupport,
     module IHP.ModelSupport,
     module IHP.FrameworkConfig,
+    module IHP.OpenApiSupport,
     module Data.Data,
     module Data.Aeson,
     module IHP.AutoRefresh.View,
@@ -50,6 +51,7 @@ import IHP.ValidationSupport
 import IHP.RouterSupport
 import IHP.ModelSupport
 import IHP.FrameworkConfig
+import IHP.OpenApiSupport
 import Data.Data
 import Data.Aeson (ToJSON (..), FromJSON (..), KeyValue (..))
 import IHP.AutoRefresh.View
diff --git a/ihp/IHP/ViewSupport.hs b/ihp/IHP/ViewSupport.hs
index 7bf2f610c..da1f605d2 100644
--- a/ihp/IHP/ViewSupport.hs
+++ b/ihp/IHP/ViewSupport.hs
@@ -1,4 +1,5 @@
 {-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE DefaultSignatures   #-}
 {-# LANGUAGE UndecidableInstances  #-}
 {-|
 Module: IHP.ViewSupport
@@ -11,6 +12,7 @@ module IHP.ViewSupport
 , Html
 , View (..)
 , JsonView (..)
+, json
 , currentViewId
 , forEach
 , isActivePath
@@ -66,7 +68,21 @@ class View theView where
 -- | Implement this for views that can be rendered as JSON.
 -- Use 'renderHtmlOrJson' in your controller to dispatch based on the Accept header.
 class JsonView theView where
-    json :: theView -> JSON.Value
+    type JsonResponse theView :: Type
+    type JsonResponse theView = JSON.Value
+
+    -- | Returns the typed JSON response payload for this view.
+    --
+    -- IHP renders JSON views by applying 'toJSON' to this value. This keeps
+    -- the rendered JSON and OpenAPI response schema tied to the same
+    -- 'JsonResponse' type.
+    jsonTyped :: theView -> JsonResponse theView
+    jsonTyped _ = error "Json View for this route is not implemented"
+
+-- | Renders a JSON view from its typed response value.
+json :: (JsonView theView, JSON.ToJSON (JsonResponse theView)) => theView -> JSON.Value
+json view = JSON.toJSON (jsonTyped view)
+{-# INLINE json #-}
 
 -- | Returns a string to be used as a html id attribute for the current view.
 -- E.g. when calling @currentViewId@ while rendering the view @Web.View.Projects.Show@, this will return @"projects-show"@
@@ -246,4 +262,4 @@ assetPath assetPath = AssetPath.assetPath theRequest assetPath
 -- The asset version can be configured using the
 -- @IHP_ASSET_VERSION@ environment variable.
 assetVersion :: (?request :: Request) => Text
-assetVersion = fromMaybe (error "assetPath middleware missing") (AssetPath.assetVersion theRequest)
\ No newline at end of file
+assetVersion = fromMaybe (error "assetPath middleware missing") (AssetPath.assetVersion theRequest)
diff --git a/ihp/Test/Test/Main.hs b/ihp/Test/Test/Main.hs
index 90c4b5608..88c4ea560 100644
--- a/ihp/Test/Test/Main.hs
+++ b/ihp/Test/Test/Main.hs
@@ -16,6 +16,7 @@ import qualified Test.Controller.NotFoundSpec
 import qualified Test.ModelSupportSpec
 import qualified Test.QueryBuilderSpec
 import qualified Test.RouterSupportSpec
+import qualified Test.OpenApiSupportSpec
 import qualified Test.ViewSupportSpec
 import qualified Test.FileStorage.ControllerFunctionsSpec
 import qualified Test.PGListenerSpec
@@ -42,6 +43,7 @@ main = hspec do
     Test.ModelSupportSpec.tests
     Test.QueryBuilderSpec.tests
     Test.RouterSupportSpec.tests
+    Test.OpenApiSupportSpec.tests
     Test.ViewSupportSpec.tests
     Test.FileStorage.ControllerFunctionsSpec.tests
     Test.Controller.CookieSpec.tests
diff --git a/ihp/Test/Test/OpenApiSupportSpec.hs b/ihp/Test/Test/OpenApiSupportSpec.hs
new file mode 100644
index 000000000..ef4a6f9d8
--- /dev/null
+++ b/ihp/Test/Test/OpenApiSupportSpec.hs
@@ -0,0 +1,497 @@
+{-# LANGUAGE AllowAmbiguousTypes #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE DeriveGeneric #-}
+
+module Test.OpenApiSupportSpec where
+
+import ClassyPrelude hiding (handle)
+import Data.Aeson qualified as JSON
+import Data.Aeson.Key qualified as Key
+import Data.Aeson.KeyMap qualified as KeyMap
+import Data.Attoparsec.ByteString.Char8 (decimal, endOfInput, string)
+import Data.Text qualified as Text
+import IHP.ControllerPrelude hiding (find, get, request)
+import IHP.Environment
+import IHP.Test.Mocking
+import IHP.ViewPrelude
+import Network.HTTP.Types
+import Network.Wai.Test
+import Test.Hspec
+import Prelude qualified
+
+data Band' = Band {id :: Id' "open_api_bands", meta :: MetaBag} deriving (Eq, Show)
+type Band = Band'
+type instance GetTableName Band' = "open_api_bands"
+type instance GetModelByTableName "open_api_bands" = Band
+type instance GetModelName Band' = "Band"
+type instance PrimaryKey "open_api_bands" = Integer
+
+data Performance' = Performance {id :: Id' "open_api_performances", meta :: MetaBag} deriving (Eq, Show)
+type Performance = Performance'
+type instance GetTableName Performance' = "open_api_performances"
+type instance GetModelByTableName "open_api_performances" = Performance
+type instance GetModelName Performance' = "Performance"
+type instance PrimaryKey "open_api_performances" = UUID
+
+data WebApplication = WebApplication deriving (Eq, Show, Data)
+
+data DocumentedController
+    = ShowBandAction {bandId :: !(Id Band), page :: !(Maybe Int), tags :: ![Text]}
+    | LegacyJsonAction
+    | WrongJsonAction
+    | WrongJsonShapeAction {bandId :: !(Id Band)}
+    deriving (Eq, Show, Data)
+
+data CustomRouteController
+    = ListCustomAction
+    | ShowCustomAction {performanceId :: !(Id Performance)}
+    deriving (Eq, Show, Data)
+
+data DocumentedCustomPathController
+    = ShowDocumentedCustomPathAction {bandId :: !(Id Band)}
+    deriving (Eq, Show, Data)
+
+data UnsupportedCustomPathApplication = UnsupportedCustomPathApplication deriving (Eq, Show, Data)
+
+data UnsupportedCustomPathController
+    = ShowUnsupportedCustomPathAction {bandId :: !(Id Band)}
+    deriving (Eq, Show, Data)
+
+data CrudNamedApiController
+    = CreateApiSessionAction
+    | CreatePipeSessionAction
+    | ShowApiSessionAction
+    deriving (Eq, Show, Data)
+
+data BandView = BandView
+    { bandId :: !(Id Band)
+    , page :: !(Maybe Int)
+    , tags :: ![Text]
+    }
+
+data BandPayload = BandPayload
+    { bandId :: !Integer
+    , page :: !(Maybe Int)
+    , tags :: ![Text]
+    }
+    deriving (Eq, Show, Generic)
+
+instance JSON.ToJSON BandPayload
+instance ToSchema BandPayload
+
+data LegacyJsonView = LegacyJsonView
+data WrongJsonShapeView = WrongJsonShapeView {bandId :: !(Id Band)}
+data DocumentedCustomPathView = DocumentedCustomPathView {bandId :: !(Id Band)}
+data UnsupportedCustomPathView = UnsupportedCustomPathView {bandId :: !(Id Band)}
+data AckView = AckView
+
+data AckPayload = AckPayload
+    { ok :: !Bool
+    }
+    deriving (Eq, Show, Generic)
+
+instance JSON.ToJSON AckPayload
+instance ToSchema AckPayload
+
+data CreateSessionRequest = CreateSessionRequest
+    { token :: !Text
+    }
+    deriving (Eq, Show, Generic)
+
+instance JSON.ToJSON CreateSessionRequest
+instance JSON.FromJSON CreateSessionRequest
+instance ToSchema CreateSessionRequest
+
+instance View BandView where
+    html BandView{..} = [hsx||]
+
+instance JsonView BandView where
+    type JsonResponse BandView = BandPayload
+
+    jsonTyped BandView{..} =
+        BandPayload
+            { bandId = unpackId bandId
+            , page
+            , tags
+            }
+
+instance View LegacyJsonView where
+    html LegacyJsonView = [hsx||]
+
+instance JsonView LegacyJsonView where
+    jsonTyped LegacyJsonView =
+        JSON.object
+            [ "legacy" JSON..= True
+            ]
+
+instance View WrongJsonShapeView where
+    html WrongJsonShapeView{..} = [hsx||]
+
+instance JsonView WrongJsonShapeView where
+    type JsonResponse WrongJsonShapeView = BandPayload
+
+    jsonTyped WrongJsonShapeView{..} =
+        BandPayload
+            { bandId = unpackId bandId
+            , page = Nothing
+            , tags = []
+            }
+
+instance View DocumentedCustomPathView where
+    html DocumentedCustomPathView{..} = [hsx||]
+
+instance JsonView DocumentedCustomPathView where
+    type JsonResponse DocumentedCustomPathView = BandPayload
+
+    jsonTyped DocumentedCustomPathView{..} =
+        BandPayload
+            { bandId = unpackId bandId
+            , page = Nothing
+            , tags = []
+            }
+
+instance View UnsupportedCustomPathView where
+    html UnsupportedCustomPathView{..} = [hsx||]
+
+instance JsonView UnsupportedCustomPathView where
+    type JsonResponse UnsupportedCustomPathView = BandPayload
+
+    jsonTyped UnsupportedCustomPathView{..} =
+        BandPayload
+            { bandId = unpackId bandId
+            , page = Nothing
+            , tags = []
+            }
+
+instance View AckView where
+    html AckView = [hsx||]
+
+instance JsonView AckView where
+    type JsonResponse AckView = AckPayload
+
+    jsonTyped AckView = AckPayload{ok = True}
+
+instance Controller DocumentedController where
+    type ControllerAction DocumentedController = ActionDefinition DocumentedController
+
+    action ShowBandAction{..} =
+        endpoint
+            |> responseView @BandView
+            |> summary "Show a band payload"
+            |> handle (pure @IO BandView{..})
+    action LegacyJsonAction =
+        legacyAction (renderHtmlOrJson LegacyJsonView)
+    action WrongJsonAction =
+        legacyAction (renderHtmlOrJson LegacyJsonView)
+    action WrongJsonShapeAction{..} =
+        endpoint
+            |> responseView @WrongJsonShapeView
+            |> handle (pure @IO WrongJsonShapeView{..})
+
+instance Controller CustomRouteController where
+    action ListCustomAction = renderPlain "ListCustomAction"
+    action ShowCustomAction{..} = renderPlain (cs (Prelude.show performanceId))
+
+instance Controller DocumentedCustomPathController where
+    type ControllerAction DocumentedCustomPathController = ActionDefinition DocumentedCustomPathController
+
+    action ShowDocumentedCustomPathAction{..} =
+        endpoint
+            |> responseView @DocumentedCustomPathView
+            |> handle (pure @IO DocumentedCustomPathView{..})
+
+instance Controller UnsupportedCustomPathController where
+    type ControllerAction UnsupportedCustomPathController = ActionDefinition UnsupportedCustomPathController
+
+    action ShowUnsupportedCustomPathAction{..} =
+        endpoint
+            |> responseView @UnsupportedCustomPathView
+            |> handle (pure @IO UnsupportedCustomPathView{..})
+
+instance Controller CrudNamedApiController where
+    type ControllerAction CrudNamedApiController = ActionDefinition CrudNamedApiController
+
+    action CreateApiSessionAction =
+        endpoint
+            |> responseView @AckView
+            |> handle \(_ :: CreateSessionRequest) ->
+                pure @IO AckView
+    action CreatePipeSessionAction =
+        endpoint
+            |> responseView @AckView
+            |> successStatus status201
+            |> successResponseDescription "Created response"
+            |> handle \(_ :: CreateSessionRequest) ->
+                pure @IO AckView
+    action ShowApiSessionAction =
+        endpoint
+            |> responseView @AckView
+            |> handle (pure @IO AckView)
+
+instance AutoRoute DocumentedController where
+    autoRoute = autoRouteWithIdType (parseIntegerId @(Id Band))
+    applyAction = applyConstr (parseIntegerId @(Id Band))
+
+instance AutoRoute CustomRouteController where
+    customRoutes = do
+        string "/custom/"
+        performanceId <- parseId
+        endOfInput
+        onlyAllowMethods [GET, HEAD]
+        pure ShowCustomAction{performanceId}
+
+    customPathTo ShowCustomAction{performanceId} = Just ("/custom/" <> cs (Prelude.show performanceId))
+    customPathTo _ = Nothing
+
+instance AutoRoute DocumentedCustomPathController where
+    autoRoute = autoRouteWithIdType (parseIntegerId @(Id Band))
+    applyAction = applyConstr (parseIntegerId @(Id Band))
+
+    customRoutes = do
+        string "/bands/"
+        bandId <- packId <$> decimal
+        endOfInput
+        onlyAllowMethods [GET, HEAD]
+        pure ShowDocumentedCustomPathAction{bandId}
+
+    customPathTo ShowDocumentedCustomPathAction{bandId} = Just ("/bands/" <> cs (Prelude.show (unpackId bandId)))
+
+instance AutoRoute UnsupportedCustomPathController where
+    autoRoute = autoRouteWithIdType (parseIntegerId @(Id Band))
+    applyAction = applyConstr (parseIntegerId @(Id Band))
+
+    customPathTo ShowUnsupportedCustomPathAction{bandId} = Just ("/unsupported-bands/" <> cs (Prelude.show (unpackId bandId)))
+
+instance AutoRoute CrudNamedApiController
+
+instance FrontController WebApplication where
+    controllers =
+        [ documentRoute @DocumentedController
+        , documentRoute @DocumentedCustomPathController
+        , documentRoute @CrudNamedApiController
+        , parseRoute @CustomRouteController
+        , swaggerUiWithOptions ((defaultSwaggerUiOptions @WebApplication){swaggerUiPath = "/docs", swaggerUiTitle = Just "Band API Docs"})
+        ]
+
+instance FrontController RootApplication where
+    controllers = [mountFrontController WebApplication]
+
+instance FrontController UnsupportedCustomPathApplication where
+    controllers = [documentRoute @UnsupportedCustomPathController]
+
+defaultLayout :: Html -> Html
+defaultLayout inner = [hsx|{inner}|]
+
+instance InitControllerContext WebApplication where
+    initContext = setLayout defaultLayout
+
+instance InitControllerContext RootApplication
+instance InitControllerContext UnsupportedCustomPathApplication
+
+testJson :: ByteString -> Session SResponse
+testJson url =
+    request $
+        setPath
+            defaultRequest
+                { requestMethod = methodGet
+                , requestHeaders = [(hAccept, "application/json")]
+                }
+            url
+
+testPostJson :: ByteString -> JSON.Value -> Session SResponse
+testPostJson url body =
+    srequest $ SRequest request (JSON.encode body)
+  where
+    request =
+        setPath
+            defaultRequest
+                { requestMethod = methodPost
+                , requestHeaders =
+                    [ (hAccept, "application/json")
+                    , (hContentType, "application/json")
+                    ]
+                }
+            url
+
+testGet :: ByteString -> Session SResponse
+testGet url = request $ setPath defaultRequest{requestMethod = methodGet} url
+
+assertJsonBody :: JSON.Value -> SResponse -> IO ()
+assertJsonBody expected response = do
+    response.simpleStatus `shouldBe` status200
+    JSON.decode response.simpleBody `shouldBe` Just expected
+
+lookupValue :: Text -> JSON.Value -> Maybe JSON.Value
+lookupValue key (JSON.Object object) = KeyMap.lookup (Key.fromText key) object
+lookupValue _ _ = Nothing
+
+lookupPathOperation :: Text -> Text -> JSON.Value -> Maybe JSON.Value
+lookupPathOperation path method spec = do
+    paths <- lookupValue "paths" spec
+    pathItem <- lookupValue path paths
+    lookupValue method pathItem
+
+lookupParameter :: Text -> JSON.Value -> Maybe JSON.Value
+lookupParameter name operation = do
+    JSON.Array parameters <- lookupValue "parameters" operation
+    parameters
+        |> toList
+        |> ClassyPrelude.find (\parameter -> lookupValue "name" parameter == Just (JSON.String name))
+
+config :: ConfigBuilder
+config = do
+    option Development
+    option (AppPort 8000)
+
+tests :: Spec
+tests = aroundAll (withMockContextAndApp RootApplication config) do
+    describe "JSON rendering" do
+        it "renders typed jsonTyped values through renderHtmlOrJson" $ withContextAndApp \application -> do
+            let expected =
+                    JSON.object
+                        [ "bandId" JSON..= (12 :: Integer)
+                        , "page" JSON..= Just (2 :: Int)
+                        , "tags" JSON..= (["rock", "jazz"] :: [Text])
+                        ]
+            runSession (testJson "test/ShowBand?bandId=12&page=2&tags=rock,jazz") application >>= assertJsonBody expected
+
+        it "keeps JSON.Value responses working through jsonTyped" $ withContextAndApp \application -> do
+            let expected = JSON.object ["legacy" JSON..= True]
+            runSession (testJson "test/LegacyJson") application >>= assertJsonBody expected
+
+        it "renders documented actions from jsonTyped so the JSON shape cannot diverge from the typed response" $ withContextAndApp \application -> do
+            let expected =
+                    JSON.object
+                        [ "bandId" JSON..= (12 :: Integer)
+                        , "page" JSON..= (Nothing :: Maybe Int)
+                        , "tags" JSON..= ([] :: [Text])
+                        ]
+            runSession (testJson "test/WrongJsonShape?bandId=12") application >>= assertJsonBody expected
+
+        it "runs inspectable endpoint actions with decoded request bodies" $ withContextAndApp \application -> do
+            let expected = JSON.object ["ok" JSON..= True]
+            runSession (testPostJson "test/CreateApiSession" (JSON.object ["token" JSON..= ("abc" :: Text)])) application >>= assertJsonBody expected
+
+        it "uses endpoint success status for inspectable actions" $ withContextAndApp \application -> do
+            response <- runSession (testPostJson "test/CreatePipeSession" (JSON.object ["token" JSON..= ("abc" :: Text)])) application
+            response.simpleStatus `shouldBe` status201
+            JSON.decode response.simpleBody `shouldBe` Just (JSON.object ["ok" JSON..= True])
+
+    describe "OpenAPI generation" do
+        it "derives AutoRoute paths, methods, params and response schemas from the controller" $ withContextAndApp \_ -> do
+            let spec = buildOpenApi RootApplication
+
+            lookupValue "openapi" spec `shouldBe` Just (JSON.String "3.0.3")
+
+            let getOperation = lookupPathOperation "/test/ShowBand" "get" spec
+            let headOperation = lookupPathOperation "/test/ShowBand" "head" spec
+
+            headOperation `shouldSatisfy` isJust
+            getOperation `shouldSatisfy` isJust
+
+            let Just operation = getOperation
+
+            let Just bandIdParameter = lookupParameter "bandId" operation
+            lookupValue "required" bandIdParameter `shouldBe` Just (JSON.Bool True)
+            (lookupValue "type" =<< lookupValue "schema" bandIdParameter) `shouldBe` Just (JSON.String "integer")
+
+            let Just pageParameter = lookupParameter "page" operation
+            lookupValue "required" pageParameter `shouldBe` Just (JSON.Bool False)
+
+            let Just tagsParameter = lookupParameter "tags" operation
+            lookupValue "explode" tagsParameter `shouldBe` Just (JSON.Bool False)
+            (lookupValue "type" =<< lookupValue "schema" tagsParameter) `shouldBe` Just (JSON.String "array")
+
+            let Just schema =
+                    lookupValue "responses" operation
+                        >>= lookupValue "200"
+                        >>= lookupValue "content"
+                        >>= lookupValue "application/json"
+                        >>= lookupValue "schema"
+            lookupValue "$ref" schema `shouldBe` Just (JSON.String "#/components/schemas/BandPayload")
+
+            let Just componentsSchemas = lookupValue "components" spec >>= lookupValue "schemas"
+            let Just bandPayloadSchema = lookupValue "BandPayload" componentsSchemas
+            lookupValue "type" bandPayloadSchema `shouldBe` Just (JSON.String "object")
+            (lookupValue "properties" bandPayloadSchema >>= lookupValue "bandId") `shouldSatisfy` isJust
+
+        it "omits undocumented custom routes from the generated spec" $ withContextAndApp \_ -> do
+            let spec = buildOpenApi RootApplication
+            lookupPathOperation "/test/ShowCustom" "get" spec `shouldBe` Nothing
+            lookupPathOperation "/custom/{performanceId}" "get" spec `shouldBe` Nothing
+
+        it "documents basic customPathTo routes verified by customRoutes" $ withContextAndApp \_ -> do
+            let spec = buildOpenApi RootApplication
+            lookupPathOperation "/test/ShowDocumentedCustomPath" "get" spec `shouldBe` Nothing
+            let Just operation = lookupPathOperation "/bands/{bandId}" "get" spec
+            let Just bandIdParameter = lookupParameter "bandId" operation
+            lookupValue "in" bandIdParameter `shouldBe` Just (JSON.String "path")
+            lookupValue "required" bandIdParameter `shouldBe` Just (JSON.Bool True)
+            (lookupValue "type" =<< lookupValue "schema" bandIdParameter) `shouldBe` Just (JSON.String "integer")
+
+        it "fails OpenAPI generation when customPathTo is not backed by customRoutes" $ withContextAndApp \_ -> do
+            evaluate (buildOpenApi UnsupportedCustomPathApplication) `shouldThrow` \(OpenApiGenerationException message) ->
+                "customRoutes does not parse that path" `Text.isInfixOf` message
+
+        it "keeps CreateApi and ShowApi action names unchanged in documented AutoRoute paths" $ withContextAndApp \_ -> do
+            let spec = buildOpenApi RootApplication
+
+            lookupPathOperation "/test/CreateApiSession" "post" spec `shouldSatisfy` isJust
+            lookupPathOperation "/test/CreatePipeSession" "post" spec `shouldSatisfy` isJust
+            lookupPathOperation "/test/CreateApiSession" "get" spec `shouldBe` Nothing
+            lookupPathOperation "/test/ShowApiSession" "get" spec `shouldSatisfy` isJust
+            lookupPathOperation "/test/ShowApiSession" "head" spec `shouldSatisfy` isJust
+            lookupPathOperation "/test/ApiSession" "post" spec `shouldBe` Nothing
+            lookupPathOperation "/test/ApiSession" "get" spec `shouldBe` Nothing
+
+        it "includes request body schemas for documented JSON actions" $ withContextAndApp \_ -> do
+            let spec = buildOpenApi RootApplication
+
+            let Just operation = lookupPathOperation "/test/CreateApiSession" "post" spec
+            let Just requestBody =
+                    lookupValue "requestBody" operation
+                        >>= lookupValue "content"
+                        >>= lookupValue "application/json"
+                        >>= lookupValue "schema"
+
+            lookupValue "$ref" requestBody `shouldBe` Just (JSON.String "#/components/schemas/CreateSessionRequest")
+
+            let Just componentsSchemas = lookupValue "components" spec >>= lookupValue "schemas"
+            let Just createSessionRequestSchema = lookupValue "CreateSessionRequest" componentsSchemas
+            lookupValue "type" createSessionRequestSchema `shouldBe` Just (JSON.String "object")
+            (lookupValue "properties" createSessionRequestSchema >>= lookupValue "token") `shouldSatisfy` isJust
+
+        it "supports request body and success metadata setters on action docs" $ withContextAndApp \_ -> do
+            let spec = buildOpenApi RootApplication
+
+            let Just operation = lookupPathOperation "/test/CreatePipeSession" "post" spec
+            let Just requestBody =
+                    lookupValue "requestBody" operation
+                        >>= lookupValue "content"
+                        >>= lookupValue "application/json"
+                        >>= lookupValue "schema"
+
+            lookupValue "$ref" requestBody `shouldBe` Just (JSON.String "#/components/schemas/CreateSessionRequest")
+
+            let Just createdResponse =
+                    lookupValue "responses" operation
+                        >>= lookupValue "201"
+
+            lookupValue "description" createdResponse `shouldBe` Just (JSON.String "Created response")
+            (lookupValue "responses" operation >>= lookupValue "200") `shouldBe` Nothing
+
+    describe "Swagger UI" do
+        it "serves the generated OpenAPI JSON from the mounted router" $ withContextAndApp \application -> do
+            response <- runSession (testGet "docs/openapi.json") application
+            response.simpleStatus `shouldBe` status200
+            Prelude.lookup hContentType response.simpleHeaders `shouldBe` Just "application/json"
+            JSON.decode response.simpleBody `shouldBe` Just (buildOpenApi WebApplication)
+
+        it "serves a Swagger UI page pointing at the generated OpenAPI JSON" $ withContextAndApp \application -> do
+            response <- runSession (testGet "docs") application
+            response.simpleStatus `shouldBe` status200
+            Prelude.lookup hContentType response.simpleHeaders `shouldBe` Just "text/html; charset=utf-8"
+            let body = cs response.simpleBody
+            Text.isInfixOf "Band API Docs" body `shouldBe` True
+            Text.isInfixOf "./openapi.json" body `shouldBe` True
+            Text.isInfixOf "SwaggerUIBundle" body `shouldBe` True
diff --git a/ihp/default.nix b/ihp/default.nix
index eaec8c842..539b46bab 100644
--- a/ihp/default.nix
+++ b/ihp/default.nix
@@ -9,6 +9,7 @@
 , http-client, http-client-tls, http-media, http-types, ihp-context
 , ihp-hsx, ihp-imagemagick, ihp-log, ihp-modal, ihp-pagehead
 , ihp-pglistener, inflections, interpolate, lib, mime-types
+, openapi3
 , minio-hs, mono-traversable, mtl, neat-interpolation, network
 , network-uri, parser-combinators, postgresql-simple
 , postgresql-simple-postgresql-types, postgresql-types, process
@@ -38,7 +39,7 @@ mkDerivation {
     http-client http-client-tls http-media http-types ihp-context
     ihp-hsx ihp-imagemagick ihp-log ihp-modal ihp-pagehead
     ihp-pglistener inflections interpolate mime-types minio-hs
-    mono-traversable mtl neat-interpolation network network-uri
+    mono-traversable mtl neat-interpolation network network-uri openapi3
     parser-combinators postgresql-simple
     postgresql-simple-postgresql-types postgresql-types process
     pwstore-fast random random-strings regex-tdfa resource-pool
@@ -62,7 +63,7 @@ mkDerivation {
     hspec http-client http-client-tls http-media http-types ihp-context
     ihp-hsx ihp-imagemagick ihp-log ihp-modal ihp-pagehead
     ihp-pglistener inflections interpolate mime-types minio-hs
-    mono-traversable mtl neat-interpolation network network-uri
+    mono-traversable mtl neat-interpolation network network-uri openapi3
     parser-combinators postgresql-simple
     postgresql-simple-postgresql-types postgresql-types process
     pwstore-fast random random-strings regex-tdfa resource-pool
@@ -86,7 +87,7 @@ mkDerivation {
     http-client http-client-tls http-media http-types ihp-context
     ihp-hsx ihp-imagemagick ihp-log ihp-modal ihp-pagehead
     ihp-pglistener inflections interpolate mime-types minio-hs
-    mono-traversable mtl neat-interpolation network network-uri
+    mono-traversable mtl neat-interpolation network network-uri openapi3
     parser-combinators postgresql-simple
     postgresql-simple-postgresql-types postgresql-types process
     pwstore-fast random random-strings regex-tdfa resource-pool
diff --git a/ihp/ihp.cabal b/ihp/ihp.cabal
index ab890ec49..aef1d41a0 100644
--- a/ihp/ihp.cabal
+++ b/ihp/ihp.cabal
@@ -105,6 +105,8 @@ common shared-properties
             , conduit-extra
             , wai-cors
             , random
+            , openapi3
+            , hspec
             , cereal
             , cereal-text
             , neat-interpolation
@@ -165,6 +167,7 @@ library
         , IHP.AuthSupport.Authentication
         , IHP.AuthSupport.Lockable
         , IHP.Controller.Param
+        , IHP.Controller.ActionDefinition
         , IHP.Controller.FileUpload
         , IHP.Controller.Redirect
         , IHP.Controller.Render
@@ -223,6 +226,7 @@ library
         , IHP.RouterSupport
         , IHP.Router.Types
         , IHP.Router.UrlGenerator
+        , IHP.OpenApiSupport
         , IHP.Prelude
         , IHP.ErrorController
         , IHP.ScriptSupport
@@ -273,6 +277,7 @@ library
     reexported-modules: IHP.PGListener
     autogen-modules: Paths_ihp
     other-modules:
+        IHP.OpenApiSupport.ActionDoc
         Paths_ihp
 
 source-repository head
@@ -301,6 +306,7 @@ test-suite tests
         Test.ModelSupportSpec
         Test.QueryBuilderSpec
         Test.RouterSupportSpec
+        Test.OpenApiSupportSpec
         Test.ViewSupportSpec
         Test.FileStorage.ControllerFunctionsSpec
         Test.Controller.CookieSpec