As libraries have begun implementation, we've started to get support requests asking how certain APIs behave and how one should interact with them. These scenarios have generally been regarding configuration so far, but users will also want this information for things like export into the LDP (and other data lake-y things) in the future.
A way of autogenerating documentation about our APIs will free up our time and allow us to lower the amount of time spent supporting users who are asking relatively basic questions.
RMB modules already generate their API which is easily accessible here on the FOLIO API Documentation site.
To start with, the following sets of APIs could be useful:
- Refdata endpoints. This is something that we've already been asked for several times by different groups.
- Terms (Custom Properties)
- Agreement lines
- Covered E-resources. We already export these, but don't have documentation about what the various fields mean and what they represent.
- Other planned export endpoints.
- Import endpoints (such as the file import for Local KB Admin). We allow people to upload files but where do they figure out what the format is? If we're going to document it for that use case, we may as well document it for the actual endpoint so it can be automated/scripted as well.
A general-purpose method of autogenerating this documentation for all endpoints is ultimately the goal here, though. Something that can be hooked into that FOLIO APIs page and perhaps Jenkins master commits. We don't want something that we'll have to keep up-to-date manually ourselves.