openedx / api-doc-tools Goto Github PK
View Code? Open in Web Editor NEWTools for writing and generating API documentation for edX REST APIs
License: Apache License 2.0
Tools for writing and generating API documentation for edX REST APIs
License: Apache License 2.0
Make sure they are findable from the API Best Practices doc.
TBD: should the bulk of the instructions be in this repo?
The edX API Documentation tools (GitHub, ReadTheDocs) are a flexible and friendly way to incrementally document HTTP APIs, allowing one to start with mostly auto-generated docs, and then use decorators to move towards fully-documented API catalogs.
Our previous strategy for generating API documentation (counting on Swagger to auto-parse the docstrings) is no longer supported.
Currently, at least edx-platform and Registrar use the library. (Registrar counts on the library to generate partner-facing API documentation). The edx-api-doc-tools library should be installed into the edx-cookiecutters so that it is available by default in new Django IDAs.
Some bits may stay in edx-platform if they are truly specific to edx-platform.
Sometimes, drf-yasg
can't figure out the appropriate serializer for a class. That's not a problem if we have a serializer on hand to pass to schema
:
@schema(responses={200: MySerializer})
def get(...):
""" My view """
For paginated views, this becomes a problem, because we don't have a paginated serializer to give schema
.
I see two solutions to this:
Why can't drf-yasg generate a correct paginated response schema? Are we missing a class variable on our views? Are we using DRF wrong?
In the case where drf-yasg just can't figure out the response schema, it'd be great to be able to do something like:
@schema(responses={200: paginate_serializer(MySerializer, MyPaginationClass)})
def get(...):
""" My paginated view """
A lot of value in documentation comes from introduction paragraphs, section structure, etc.
Right now, the /api-docs
page is a big list of endpoints.
How can we allow for better customization of the /api-docs
page to make it a better experience for consumers of API documentation?
There is a lot of room for discovery and experimentation here.
Should we freeze the API docs for each release?
I wanted to add this dependency to edx-analytics-data-api in https://github.com/edx/edx-analytics-data-api/pull/329, but some of the APIs there are not in the root path /api
, for instance there are some APIs under /enterprise/api/ that are taken from https://github.com/edx/edx-enterprise-data
How should I do that?
I think that we could make that the ApiSchemaGenerator takes the root path from the django settings or as a parameter passed when it is being instantiated.
What do you think?
Different versions of drf-yasg
may break or change the behavior of api-doc-tools
.
Thus, if drf-yasg
is upgraded in a service, it may seem like api-doc-tools
changed, even if that package's version did not change.
I recommend that we require a specific version of drf-yasg
as an installation requirement of edx-api-doc-tools
. Ideally, this pin could be continuously updated by make upgrade
PRs in this repo.
As far as I know, no edX repository other than this one directly depends on drf-yasg
, so we shouldn't see issues with conflicting version constraints.
This should be part of #4, and included as part of the RTFD push.
Should we hide unsupported docs? Or just mark them?
This repository is a depedency of edx-platform and needs to be upgraded to Python 3.11 before
the Readwood release is cut (mid-April).
I believe this is implemented in edx-platform
, but it needs to be pulled into this library.
It's common hard-wrap docstrings to abide by max-line-length conventions:
class MyView(...):
def get(...):
"""
Do a thing.
This is my long and very helpful description of what my endpoint is for
which I am manually breaking into two lines.
"""
which yields:
This is my long and very helpful description of what my endpoint is for
which I am manually breaking into two lines.
It'd be nice to instead see the soft-wrapped version in the output:
This is my long and very helpful description of what my endpoint is for which I am manually breaking into two lines.
Of course, double-line breaks should still be regarded as actual line breaks in the output.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.