REST API documentation consistency improvements about auth HOT 3 CLOSED

Please avoid using only automated tools without human review.

The OpenAPI spec is the documentation. Not everything is for README, and Supabase docs usually exist in https://supabase.com/docs.

from auth.

The issue description does seem to accurately point out some errors/inconsistencies with the OpenAPI spec vs the readme though.

from auth.

Thank you for your feedback, @hf . I appreciate the clarification that the OpenAPI spec serves as the primary documentation and that not all endpoints are intended for the README. However, it does seem that the OpenAPI spec and the README have at least some overlap.

I understand the concern about relying solely on automated tools without human review. However, the intention behind this tool is to assist maintainers by identifying potential discrepancies that might otherwise be overlooked, thus facilitating a more efficient review process. Here are a few points to consider in defense of this approach:

1. Efficiency: Automated tools can quickly scan and compare large documents, identifying inconsistencies in a fraction of the time it would take a human. This allows maintainers to focus their efforts on verifying and correcting issues rather than identifying them.
2. Scalability: As projects grow, the documentation tends to become more complex. An automated tool can scale with the project, ensuring continuous monitoring of documentation consistency across all updates.
3. Support for Human Review: The tool is designed to support, not replace, human review. By flagging potential issues, it provides a starting point for maintainers to perform more detailed examinations and make informed decisions.

Additionally, this tool is still in the development process, and the purpose of raising this issue is to gather feedback on how to make it better. Input from experienced teams like yours is invaluable in fine-tuning the tool to ensure it aligns with practical needs and workflows. Your insights can help refine its functionality, making it a more effective and reliable asset for documentation maintenance.

To make this tool more effective and aligned with your practices, any specific guidance on how you differentiate which endpoints should be included in the README versus the OpenAPI spec would be very valuable.

Thank you for considering these points and also thank you @bnjmnt4n for acknowledging the identified inconsistencies. I'm eager to refine this tool to better support your documentation maintenance process and ensure it complements the excellent work your team is doing.

from auth.