diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx index 978a715ce..8ed84caa6 100644 --- a/api-playground/openapi-setup.mdx +++ b/api-playground/openapi-setup.mdx @@ -322,6 +322,90 @@ To organize multiple OpenAPI specifications in separate sections of your documen The `directory` field is optional and specifies where generated API pages are stored in your docs repo. If not specified, defaults to the `api-reference` directory of your repo. +#### Nested groups with endpoints + +For large APIs with many endpoints, you can create multiple levels of nesting by placing groups within groups. Each nested group can reference specific endpoints from your OpenAPI specification. + +```json +"navigation": { + "tabs": [ + { + "tab": "API Reference", + "openapi": "/path/to/openapi.json", + "groups": [ + { + "group": "Real-Time Communications", + "groups": [ + { + "group": "Programmable Voice", + "groups": [ + { + "group": "Call Control", + "pages": [ + "GET /calls", + "POST /calls", + "POST /calls/{call_id}/actions/answer", + "POST /calls/{call_id}/actions/hangup" + ] + }, + { + "group": "Conferences", + "pages": [ + "GET /conferences", + "POST /conferences", + "POST /conferences/{id}/actions/join" + ] + } + ] + }, + { + "group": "Messaging", + "pages": [ + "POST /messages", + "GET /messages/{id}" + ] + } + ] + }, + { + "group": "Phone Numbers", + "groups": [ + { + "group": "Number Management", + "pages": [ + "GET /phone_numbers", + "GET /phone_numbers/{id}", + "PATCH /phone_numbers/{id}" + ] + }, + { + "group": "Number Search", + "pages": [ + "GET /available_phone_numbers" + ] + } + ] + } + ] + } + ] +} +``` + +This creates a navigation hierarchy like: +- **Real-Time Communications** + - **Programmable Voice** + - **Call Control** + - GET /calls + - POST /calls + - ... + - **Conferences** + - GET /conferences + - ... + - **Messaging** + - POST /messages + - ... + ### Selective endpoints When you want more control over where endpoints appear in your documentation, you can reference specific endpoints in your navigation. This approach allows you to generate pages for API endpoints alongside other content. You can also use this approach to mix endpoints from different OpenAPI specifications.