search

USGS-WiM / cbrsservices_django

Backend for CBRS project
0 stars 0 forks source link

Stand-up service documentation page #69

Open HansVraga opened 5 years ago

HansVraga commented 5 years ago

@kjacobsen16 consult @lprivette on what tools to use to put together a service documentation page for a Django Rest Framework project.

lprivette commented 5 years ago

For Merlin services, we used https://www.drfdocs.com/.

It's not the most customizable, but it's super fast to setup and ship it.

This commit https://github.com/USGS-WiM/merlin_django/commit/f21a94c453d95d60fd2dce81248aa11a2beebd66 shows most of what I did to set it up and how you add description to the endpoints.

aaronstephenson commented 5 years ago

Just chiming in quickly, then I'm going back to vacation...

DRF has a page dedicated to this topic: https://www.django-rest-framework.org/topics/documenting-your-api/

It has a built-in documentation option, which we're trying to use on WHISPers (tho with some stumbling blocks). The next release of DRF, 3.10, will completely change the built-in documentation feature from being based on their custom CoreAPI to the standard OpenAPI, which should solve the problems we've encountered so far.

No release data has been announced yet, but it has to be soon: https://www.django-rest-framework.org/community/release-notes/#3100 https://github.com/encode/django-rest-framework/milestone/69?closed=1

That said, if 3.10 doesn't solve the problems we've found with the built-in documentation feature, we should explore other options, probably something else from the list on the DRF documentation topic page.

kjacobsen16 commented 5 years ago

@aaronstephenson I'm getting an issue trying to set this up. The current issue I'm having is that from rest_framework.compat import uritemplate is returning None. That's gotta be an issue on their end right? https://github.com/encode/django-rest-framework/blob/master/rest_framework/compat.py#L102-L106

aaronstephenson commented 5 years ago

I took a look thru the DRF docs and found this: https://www.django-rest-framework.org/community/release-notes/#3101

Require uritemplate for OpenAPI schema generation, but not coreapi.

which appears to be a python library: https://pypi.org/project/uritemplate/

Easy to install, just pip install uritemplate

And now it's working!

aaronstephenson commented 5 years ago

Release 1.3.0 (de9f7ad) has the basics all set up, so the next step will be for someone (@kjacobsen16?) to actually go thru the views.py file and write the documentation for each endpoint and field and custom action.

Also, we will want to decide which UI we like better, Swagger or ReDoc.

aaronstephenson commented 5 years ago

Swagger-UI: https://cbrstest.wim.usgs.gov/cbrsservices/swagger-ui/

ReDoc: https://cbrstest.wim.usgs.gov/cbrsservices/redoc/

aaronstephenson commented 2 years ago

I think this stalled. But if this ever gets revisited, DRF now automatically creates its own documentation. so we would simply have to write more detailed info where needed (rather than standing up a 3rd party solution).