openedx / api-doc-tools Goto Github PK

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.

• Auto-build docs on PRs.
• Eventually, fail PRs if docs don't build
• In IDAs, push docs on releases (which should be tagged!)
• In edx-platform, on master merges or weekly or release, push docs to RTFD

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:

1. Help drf-yasg figure out paginated serializers better

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?

2. Provide a manual paginate_serializer function as a fall-back

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 """

• Eng All-Hands?
• Lunch-Learn?

• The TOC isn't right
• Should there be introductory words?

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).

• Requirements are compiled with Python 3.8
• Tests are run on Python 3.8 and 3.11
• (Optional) Tests are also run with 3.12 and passing or 3.12 issues are ticketed.
• Classifiers in setup.py setup.cfg or pyproject.toml indicate Python 3.11 support
• A new version is release to PyPI
• A PR is merged to edx-platform to use the new version

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.