API documentation

Classification

• Difficulty: Easy
• Skills needed: Python, Django
• Length: Medium (~175 hours)

The Problem

• Mathesar backend written in Django uses an JSON content-type API to communicate with the frontend client. This API is not properly documented which makes it harder for someone outside Mathesar to understand the APIs and use them.

Feature Description

• We should be able to automatically generate the API documentation based backend implementation
• It should be easy to manually override the automatic API inference if the inference is not correct.
• The generated documentation should be easy to understand for the users
• The API generator should be compatible with Mathesar’s license (GPLv3).
• The API generator should be easy to integrate with Django
• The API format should be a well-defined standard supported by a good community

Tasks

1. Integrate the API generator with our backend codebase written in Django and Django Rest framework.
2. Make sure the inferred APIs are correct and override them if necessary.
3. Set up the CI to generate the API documentation automatically if needed.

Expected Outcome

• The API documentation should be automatically generated by inferring the backend codebase without a lot of manual intervention
• The API documentation should be in an easy to consume format like JSON, YAML.

Application Tips

• Demonstrate proficiency with the required skills.
• Present some preliminary research into available API formats

Resources

• DRF’s “Documenting Your API” page
• Open API is one such format that fits with above requirements.
• DRF Spectacular is a library for Django Rest framework to generate Open API spec

Mentors

Primary Mentor: Mukesh Secondary Mentor(s): Kriti