Motivation

To ensure our Open Data API is comprehensively documented, easily discoverable, and maintainable by creating a complete Swagger specification with role-based documentation and clear contribution guidelines.

Current State

• Technology: We use a swagger.yaml file to define our API, which is rendered as interactive documentation in Next.js.
• Configuration: The interactive API documentation is linked in the site footer, but the swagger.yaml file is incomplete—key endpoints like /api/admin, /api/consultations, and /api/auth are missing.
• Security Concern: Admin routes are mixed with public routes without proper access control or documentation separation.
• Issue: Users and contributors cannot get a full picture of the API's capabilities and there are no clear guidelines on how to document new endpoints as they are added.

Proposed Outline

1. Conduct a Full API Audit: Systematically compare the endpoints in src/app/api/ with the swagger.yaml file to identify all undocumented routes, categorizing them by access level (public, admin, internal).

2. Implement Role-Based Documentation:

   • Create separate Swagger specifications or implement dynamic filtering based on user authentication
   • Design the /docs endpoint to show different API documentation based on user privileges
   • Consider serving different documentation URLs (e.g., /docs/admin for admin endpoints)

3. Complete the Swagger Specification: Update swagger.yaml with all missing paths, operations, parameters, and schemas, ensuring proper tagging and security definitions for different access levels.

4. Implement Dynamic Documentation Serving:

   • Modify the Next.js /docs route to check user authentication/authorization
   • Filter or conditionally render API endpoints based on user roles
   • Ensure admin routes are only visible to authenticated admin users

5. Improve Discoverability: Add a dedicated section to the main /docs page that introduces the Open Data API.

6. Create an API Contribution Guide: Create a new guide at docs/guides/api-documentation-guide.md. This document should outline:

   • The process for adding or updating API documentation when a new endpoint is created
   • Best practices for categorizing endpoints by access level and properly tagging them
   • Security considerations for documenting admin vs public endpoints
   • Instructions for implementing role-based documentation filtering
   • Guidelines for writing clear descriptions for paths, parameters, and schemas
   • Instructions for LLMs on how to approach and maintain the API documentation

Technical Considerations

• Implement server-side filtering of OpenAPI specs based on user context
• Consider using Next.js middleware or API route guards to control documentation access
• Ensure proper caching strategies for user-specific documentation
• Test all permission combinations to verify correct endpoint visibility