Support for request and response body examples

[lcawl]

🚀 Feature Proposal

It would be useful to be able to attach examples for any request and response specifications.

Motivation

OpenAPI specifications make use of examples to demonstrate valid use cases.
They are also useful for validating the accuracy of the specification.

Example

There are some examples for Kibana alerting OAS in https://github.com/elastic/kibana/tree/main/x-pack/plugins/alerting/docs/openapi/components/examples

They can be validated against the specification by using commands like these:

 npx swagger-cli validate entrypoint.yaml
npx @redocly/cli lint bundled.json

... which generate errors and warnings if the examples don't align with the specifications.

Per discussions at recent conference, it would be very nice if these examples were somehow tested against the code not just validated against the specification. There was discussion that this could be accomplished by validating them as part of the flight recorder(?), but I have no further details about this proposal.

[lcawl]

My hope is that this can be as simple as creating (one or many) JSON/YAML files alongside the specifications, which contain examples for that request or response body.

For example, in the https://github.com/elastic/elasticsearch-specification/tree/main/specification/ml/put_job folder, it would be nice to simply add a file that contains the examples from the docs, in a format something like this:

MlPutJobRequestExample1.json:

{
  "summary": "Create an anomaly detection job and datafeed.",
  "description": "An optional additional description that can contain commonmark syntax.",
  "value":
    {
      "analysis_config": {
        "bucket_span": "15m",
        "detectors": [
          {
            "detector_description": "Sum of bytes",
            "function": "sum",
            "field_name": "bytes"
          }
...

MlPutJobResponseExample1.json:

{
  "summary": "A successful response with details about the new anomaly detection job. ",
  "value":
    {
    "job_id" : "test-job1",
    "job_type" : "anomaly_detector",
    "job_version" : "8.4.0",
    "create_time" : 1656087283340,
    "datafeed_config" : {
      "datafeed_id" : "datafeed-test-job1",
      "job_id" : "test-job1",
      "authorization" : {
        "roles" : [
          "superuser"
        ]
      ...
}

However, if the information is more re-usable if the file contains only the request or response (and the summary and description are defined somewhere else in the typescript file, for example), that's fine by me too.

Then this information would be output in the *openapi.json file something like this (as described in https://spec.openapis.org/oas/v3.0.3#example-object)

...
"operationId": "ml-put-job",
"requestBody": {
  "content": {
    "application/json": {
      "schema": { ... },
      "examples": {
          "ml.example_name":
             "summary": "...",
             "description": "Optional...",
             "value": {
               ....

[pquentin]

I like the idea a lot, but am wondering about the duplication of content. Is there a way to achieve your goal without duplicating all the current Elasticsearch examples, and thus having to maintain two versions of them?

It seems possible based on our existing automation to generate all files like MlPutJobResponseExample1.json with a script, and update them periodically.

[lcawl]

I like the idea a lot, but am wondering about the duplication of content. Is there a way to achieve your goal without duplicating all the current Elasticsearch examples, and thus having to maintain two versions of them?

My vision is that ultimately they wouldn't be duplicated since they will no longer exist in the manually-maintained documentation. All of the API docs pages that currently exist will not be migrated to the new docs system, so these examples will only exist in the docs that are generated from the openAPI specs.

This is complicated a little bit by the fact that the Elasticsearch Guide currently mixes longer-form examples in with the API reference content. In those cases, we'll be extricating those flows into new "how-to" type longer-form examples in the new docs system. So yes, all of the examples will be carried forward either in the generated API docs or the manually-maintained conceptual/how-to docs, but the goal is to not have any duplication.

If I've misunderstood and there is some other place you're aware of where this duplication issue would arise (e.g. in the client docs?), let me know!

[pquentin]

Thanks for the reply! You're more familiar than me with this, sorry for the misunderstanding. And thanks for the clarifications!

[lcawl]

There's another option for where we could publish examples (and in this case have additional language support) with the following extension: https://docs.bump.sh/help/specification-support/doc-code-samples/

It doesn't seem to provide a long-form description field (like in https://spec.openapis.org/oas/latest#example-object), however, so if we love the multi-language aspect but want the additional description we might need to open an enhancement request.

[lcawl]

FYI Per https://typespec.io/docs/getting-started/typespec-for-openapi-dev#response-object TypeSpec doesn't support response body examples yet. I assume the same must be true for request body examples.

[lcawl]

I've drafted a way to (temporarily?) append examples via overlays in #2144

[lcawl]

A better solution than overlays has now been implemented via #3737