ihrm/horilla_api/README_API_DOCS.md

Horilla API Documentation

This document provides information on how to use and maintain the API documentation for Horilla HRMS.

Accessing API Documentation

The API documentation is available at the following URLs:

• Swagger UI: /api/swagger/ - Interactive documentation with testing capabilities
• ReDoc: /api/redoc/ - Clean, responsive documentation for easier reading
• JSON Schema: /api/swagger.json - Raw schema for integration with other tools

Features

• Interactive Documentation: Test API endpoints directly from the browser
• Module Organization: Endpoints are grouped by module (employee, attendance, etc.)
• Authentication Support: Bearer (JWT) only. Basic authentication is disabled.
• Request/Response Examples: Clear examples of data formats
• Versioning: API versions are clearly indicated

For Developers: Adding Documentation to New Endpoints

Using the document_api Decorator

from horilla_api.docs import document_api

class MyAPIView(APIView):
    @document_api(
        operation_description="Description of what this endpoint does",
        request_body=MyRequestSerializer,
        responses={
            200: MyResponseSerializer,
            400: "Bad request error description"
        },
        tags=['Module Name']
    )
    def get(self, request):
        # Your view logic here
        pass

Common Parameters

For paginated list views:

@document_api(
    operation_description="List all items with pagination",
    responses={200: MySerializer(many=True)},
    query_params='paginated'
)

Maintaining Documentation

• Documentation automatically updates when API endpoints change
• Security schemes (Bearer/JWT) are configured in rest_conf.py
• Basic authentication has been removed across all interfaces`
• Module tags are defined in horilla_api/docs.py

Testing Documentation

1. Start the development server
2. Navigate to /api/swagger/ or /api/redoc/
3. Verify all endpoints are properly documented
4. Test authentication flows
5. Check that all modules are properly organized

Troubleshooting

If endpoints are not appearing in documentation:

• Ensure the URL is included in the patterns list in horilla_api/urls.py
• Check that the view is using proper decorators
• Verify the serializer is correctly defined

If you see a Basic authorization option in Swagger:

• Clear your browser cache and refresh /api/swagger/
• Confirm SWAGGER_SETTINGS only contains the Bearer scheme