Home Arrow Icon Knowledge base Arrow Icon Global Arrow Icon What are the best practices for documenting backend routes in Statamic


What are the best practices for documenting backend routes in Statamic


here are the best practices for documenting backend routes in Statamic:

1. Use Artisan CLI: Leverage Laravel's Artisan command-line interface to list and inspect all registered routes, including Statamic's control panel routes. The `php artisan route:list` command can provide a comprehensive overview of your application's routes.

2. Leverage Laravel Debugbar: The Laravel Debugbar package can be a valuable tool for debugging and inspecting your application's routes, including Statamic's control panel routes. It provides a web-based interface to view and interact with your routes.

3. Document Routes in Code: Ensure that your custom Statamic routes, including control panel routes, are well-documented in your code. This can be done by adding PHPDoc comments above your route definitions in the `routes/statamic.php` file.

Example:

php
   /**
    * Display the Statamic control panel dashboard.
    *
    * @return \Illuminate\View\View
    */
   Route::statamic('cp', 'statamic.cp.dashboard');
   

4. Use Markdown Documentation: Consider creating a Markdown-formatted documentation file, such as `ROUTES.md`, to provide a comprehensive overview of your Statamic-integrated application's routes. This can include details like route URIs, HTTP methods, controller actions, and any relevant notes or examples.

5. Leverage Postman or Similar Tools: Use API testing tools like Postman to document and test your Statamic control panel routes. You can create collections and environments in Postman to manage and execute your route tests, and export the documentation for sharing.

6. Integrate with Statamic's Control Panel: Statamic's control panel provides a built-in "Routes" section where you can view and manage your application's routes. Consider leveraging this feature to document and organize your Statamic-specific routes.

7. Utilize Statamic's Bonus Routes Addon: If you're using the "Bonus Routes" addon for Statamic, be sure to document how you've extended your application's routing, including any custom collection or taxonomy-based routes.

By following these best practices, you can ensure that your Statamic-integrated application's backend routes are well-documented, making it easier for developers to understand, maintain, and extend the application's functionality.

Citations:
[1] https://statamic.dev/routing
[2] https://v2.statamic.com/routing
[3] https://statamic.dev/controllers
[4] https://laracasts.com/discuss/channels/general-discussion/whats-the-best-way-to-document-my-route-endpoints
[5] https://statamic.com/addons/jacksleight/bonus-routes