CCF icon indicating copy to clipboard operation
CCF copied to clipboard

Better example requests/responses in OpenAPI-generated docs

Open letmaik opened this issue 5 years ago • 0 comments

Part of https://github.com/microsoft/CCF/issues/1918.

The OpenAPI Specification is a key element of the Azure SDK plan and essential to improving the documentation, usability and discoverability of services.

https://microsoft.github.io/CCF/main/operations/operator_rpc_api.html

Some endpoints have bad auto-generated examples, for example config is empty.

There is the question of whether examples should become part of the OpenAPI definition itself or are purely a documentation artifact. In the latter case we could postprocess the OpenAPI definition (before handing it to sphinx) by filling in sample requests/responses scraped from e2e tests. Fwiw: Specs in https://github.com/Azure/azure-rest-api-specs/tree/master/specification generally do contain examples, via x-ms-examples (because everything is OpenAPI 2.0 which didn't have a great way to provide examples), e.g attestation services. Those specs are not served as part of a live endpoint, but just dumped to GitHub, which provides more freedom in how large those specs can be.

NOTE: Services built with CCF can still publish their own OpenAPI document (independent of what's auto-generated by CCF) with extensive samples etc. This issue is mostly about making the CCF docs better.

letmaik avatar Nov 25 '20 17:11 letmaik