API Documentation

[td-usds]

We currently lack a public documentation of our API Surface.
We should consider providing this documentation in an open, machine-readable format (e.g. OpenAPI, others... )

[MauriceReeves-usds]

Yes. Let's make this automatic, similar to how we do the schema documentation.

[td-usds]

We have a couple of possible approaches:

• check out existing tools that can generate this for us based on either static code analysis or by using reflection on top of the compiled code
• Write a tool ourselves that does one of the above
• Write the documentation manually (using an editor tool)

Any automatic approach this will only get us halfway down the road, namely the function routes and their parameters/requirements (verb, auth, name). It will not get us the return values from the endpoints: we currently return (almost everywhere if not just plain everywhere) HttpResponseMessage instead of strongly typed objects that could be inspected. In some cases, the program logic determines what the actual shape is of what gets returned. We'd have to do an inordinate amount of work to make this automatic.
We would then have to augment this with human work to figure out what gets returned when by which function.

[td-usds]

We currently have prime-router/docs/openapi.yml but I'm not sure how up to date this is