cloudflare / cloudflare/chanfana

Love Chanfana but is this possible? (Nested routes description)

Open
#158 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
766
Forks
70
Avg merge
25m
Merged PRs (30d)
4

Description

Hi love Chanfana, great work.

We have v1 and v2 nested routes working side by side and both are added to the base/root router and would be beyond awesome if both could have description in the root .. like a summary root docs describing both v1 and v2 somehow if its even a part of openapi ??? I have no clue ...

when doing this we get root.com/docs and then we get individual docs for root.com/v1/docs and root.com.com/v2/docs and that is awesome .. but the root.com/docs don´t clearly describe v1 and v2 its just one big thing .. so how do you or others handle this .. ? of you want a root docs that describe that you have multiply version endpoints , or maybe it is beyond the scope of openapi ?

const router_v1 = fromIttyRouter(Router({ base: "/v1" }), {
base: "/v1",
schema: {
info: {
title: "API 1",
description:
"Backend 1 .",
version: "v1.0.2",
},
},
});

const router_v2 = fromIttyRouter(Router({ base: "/v2" }), {
base: "/v2",
schema: {
info: {
title: "API 2",
description:
"Backend 2 .",
version: "v1.0.1",
},
},
});

Contributor guide

Open the contributing guide

Research direction

Start by reviewing how the root router combines the v1 and v2 routers and how their OpenAPI schemas produce /docs, then compare that with the separate /v1/docs and /v2/docs examples in the issue. The work is done when the root documentation clearly describes both API versions while preserving the individual documentation routes.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.