examples: writing an API for the Apache Kafka: add a root handler for routes documentation to make navigation easier and add some other methods that may find them useful for request state and routes description

Former-commit-id: 3775aab2386051b23e127ccc9e3a6accdfdee6d0

core/router/api_builder.go

@@ -437,6 +437,7 @@ func (api *APIBuilder) GetRoute(routeName string) *Route {
 // One note: "routeName" should be case-sensitive. Used by the context to get the current route.
 // It returns an interface instead to reduce wrong usage and to keep the decoupled design between
 // the context and the routes.
+// Look `GetRoutesReadOnly` to fetch a list of all registered routes.
 //
 // Look `GetRoute` for more.
 func (api *APIBuilder) GetRouteReadOnly(routeName string) context.RouteReadOnly {
@@ -447,6 +448,24 @@ func (api *APIBuilder) GetRouteReadOnly(routeName string) context.RouteReadOnly
 	return routeReadOnlyWrapper{r}
 }
 
+// GetRoutesReadOnly returns the registered routes with "read-only" access,
+// you cannot and you should not change any of these routes' properties on request state,
+// you can use the `GetRoutes()` for that instead.
+//
+// It returns interface-based slice instead of the real ones in order to apply
+// safe fetch between context(request-state) and the builded application.
+//
+// Look `GetRouteReadOnly` too.
+func (api *APIBuilder) GetRoutesReadOnly() []context.RouteReadOnly {
+	routes := api.GetRoutes()
+	readOnlyRoutes := make([]context.RouteReadOnly, len(routes))
+	for i, r := range routes {
+		readOnlyRoutes[i] = routeReadOnlyWrapper{r}
+	}
+
+	return readOnlyRoutes
+}
+
 // Use appends Handler(s) to the current Party's routes and child routes.
 // If the current Party is the root, then it registers the middleware to all child Parties' routes too.
 //

core/router/route.go

@@ -114,7 +114,7 @@ func (r Route) String() string {
 		r.Method, r.Subdomain, r.Tmpl().Src)
 }
 
-// Tmpl returns the path template, i
+// Tmpl returns the path template,
 // it contains the parsed template
 // for the route's path.
 // May contain zero named parameters.
@@ -249,3 +249,11 @@ func (rd routeReadOnlyWrapper) Path() string {
 func (rd routeReadOnlyWrapper) Trace() string {
 	return rd.Route.Trace()
 }
+
+func (rd routeReadOnlyWrapper) Tmpl() macro.Template {
+	return rd.Route.Tmpl()
+}
+
+func (rd routeReadOnlyWrapper) MainHandlerName() string {
+	return rd.Route.MainHandlerName
+}