Added description strings for almost all the request and response
fields of all endpoints.
I didn't describe all the possible items enum values. That's going
to be very long, and I think is best left for its own separate
page. I'll add a link to that page from the doc string, once it's
ready.
There are some other OpenAPI hygiene changes like adding summaries for
endpoints (which makes them show up better in doc generators), and
adding operation IDs.
I snuck in two substantive changes:
The same schema that represents authorities in the backend JSON data
was being used to represent them in the API. However, the JSON has
more fields than we want to expose in the API, so create a new
schema for authorities that excludes them.
Remove the include_beta_states parameter from the utilities
endpoint, since it's not read anymore. I already deployed a change
to the embed to stop passing it, and made sure PEP doesn't use it.
Test Plan
Use a work-in-progress script I have that merges the spec generated
from /spec.json into Zuplo's config file. The result is deployed
here:
That doesn't show the descriptions of response fields and subfields (a
known shortcoming of Zuplo). However, you can use third-party doc
generator tools with the OpenAPI spec. Here are two examples:
Description
Added description strings for almost all the request and response fields of all endpoints.
I didn't describe all the possible
itemsenum values. That's going to be very long, and I think is best left for its own separate page. I'll add a link to that page from the doc string, once it's ready.There are some other OpenAPI hygiene changes like adding summaries for endpoints (which makes them show up better in doc generators), and adding operation IDs.
I snuck in two substantive changes:
The same schema that represents authorities in the backend JSON data was being used to represent them in the API. However, the JSON has more fields than we want to expose in the API, so create a new schema for authorities that excludes them.
Remove the
include_beta_statesparameter from the utilities endpoint, since it's not read anymore. I already deployed a change to the embed to stop passing it, and made sure PEP doesn't use it.Test Plan
Use a work-in-progress script I have that merges the spec generated from
/spec.jsoninto Zuplo's config file. The result is deployed here:https://api-main-4ba10f3.d2.zuplo.dev/docs
That doesn't show the descriptions of response fields and subfields (a known shortcoming of Zuplo). However, you can use third-party doc generator tools with the OpenAPI spec. Here are two examples:
In both of those, enter this URL in the "try it" box to see the docs:
https://api-main-4ba10f3.d2.zuplo.dev/spec.json