[ENHANCEMENT] Add Comprehensive OpenAPI/Swagger Documentation for REST APIs Fixes #541

[shivraj1182]

Summary

This PR implements comprehensive OpenAPI/Swagger documentation for BuffaLogs REST APIs as requested in #541.

Changes Made

1. Added drf-spectacular dependency (requirements.txt)

   • Added drf-spectacular>=2.0.0 for OpenAPI schema generation

2. Configured settings (settings.py)

   • Added drf_spectacular to INSTALLED_APPS
   • Configured REST_FRAMEWORK with DEFAULT_SCHEMA_CLASS
   • Added SPECTACULAR_SETTINGS with API metadata (title, description, version)

3. Added documentation endpoints (urls.py)

   • /api/schema/ - OpenAPI schema endpoint
   • /api/docs/ - Interactive Swagger UI documentation
   • /api/redoc/ - Alternative ReDoc documentation interface

Testing

After deployment, the following endpoints will be available:

• /api/docs/ - Interactive Swagger UI for API testing
• /api/redoc/ - Alternative ReDoc interface
• /api/schema/ - Raw OpenAPI schema (JSON)

Benefits

• Improved Developer Experience: Interactive API documentation for testing without reading source code
• Better Integration: External tools can use the OpenAPI spec for integration
• Self-Documenting: Reduces support burden with comprehensive API documentation
• Industry Standard: Follows OpenAPI specification standards

Related Issue

Closes #541

Happy to make any adjustments based on your feedback!

[shivraj1182]

Hey @Lorygold! I've implemented the required changes that issue #541 addresses. If anything looks off, I'd be happy to make suitable adjustments. Looking forward to your review!
Thanks for maintaining such a wonderful project.

[Lorygold]

ERROR: No matching distribution found for drf-spectacular>=2.0.0

Then, does it work locally?

[shivraj1182]

ERROR: No matching distribution found for drf-spectacular>=2.0.0

Then, does it work locally?

Hi @Lorygold! I've fixed the issue by updating the drf-spectacular version from >=2.0.0 to >=0.28.0 in the requirements.txt file.

The version 2.0.0 doesn't exist on PyPI - the latest available version is 0.28.0 (released November 2024). That's why it didnt work locally! This should resolve the CI failure.

[Lorygold]

@lucaCigarini please run the CI

[lucaCigarini]

I'm afraid I cannot run CI manually. The author needs to push another commit (even an empty one like this git commit --allow-empty -m "Your commit message")

[shivraj1182]

I'm afraid I cannot run CI manually. The author needs to push another commit (even an empty one like this git commit --allow-empty -m "Your commit message")

Hey @lucaCigarini Hello! and thanks for pointing out! Let me know if something else is needed.

[Lorygold]

@shivraj1182 run linters (isort in particular) as defined in the CONTRIBUTING file, because an error occured:
CI error link