Prior to this change information about the Charging Module API and its functionality had to be gleaned from a number of sources
a spreadsheet of endpoints known as the 'API catalogue'
a spreadsheet of information about the fields known as the 'master data specification'
a one off spreadsheet of example requests and responses
a Postman collection of requests
the source code
As a new team trying to get a handle on what it could do we went through each endpoint and used the OpenAPI Specification to record our findings. We knew by doing so we could not only better record the details for each endpoint. But with a completed spec we could take advantage of other tools to automatically produce documentation and example requests, from which we could do even more.
So this change brings in what we've captured. Some key things to note
the OpenAPI spec supports use of references. Though a JSON thing they are supported in the YML version as well. Most examples, tutorials and tools assume a single file but we knew it would be unworkable if that was the case. So the file is broken up. However, we uses tools to generate a single file from our files as a number of tools only support importing a single dereferenced file
only 200 responses
the API returns 400 and 500 responses in a number of cases. However, as a first pass we have only had the time and resource to capture 200 type responses from the API
versioning
we fully expect to include Swagger within the Charging Module API in the future which should mean the API can document and describe itself, as well as derive the documentation version from the app version. Till then we set the OpenAPI spec version to match the latest GitHub release version. In the meantime we may make corrections and amendments to the spec files but we will not bump the version until we create a new git tag in the project
our master data specification document is the primary source
most information is cleaned from the master data specificaton along with the API catalogue. We have tried to validate it using actual requests but errors and omissions are likely to exist
Prior to this change information about the Charging Module API and its functionality had to be gleaned from a number of sources
As a new team trying to get a handle on what it could do we went through each endpoint and used the OpenAPI Specification to record our findings. We knew by doing so we could not only better record the details for each endpoint. But with a completed spec we could take advantage of other tools to automatically produce documentation and example requests, from which we could do even more.
So this change brings in what we've captured. Some key things to note
use of schema references
only 200 responses
versioning
our master data specification document is the primary source