Allow custom schema examples in OpenAPI format (#616)

* Custom schema examples

* Examples field only valid in media object

* linting

* Update README.md

Co-authored-by: Manuel Spigolon <behemoth89@gmail.com>

* Fix example

* Support examples in response

* Examples in params

* Fix typo

* Update readme

Co-authored-by: Manuel Spigolon <behemoth89@gmail.com>

Author: mxck

README.md

@@ -726,6 +726,140 @@ You can integration this plugin with ```@fastify/helmet``` with some little work
 })
 ```
 
+<a name="schema.examplesField"></a>
+### Add examples to the schema
+
+Note: [OpenAPI](https://swagger.io/specification/#example-object) and [JSON Schema](https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.5) have different examples field formats. 
+
+Array with examples from JSON Schema converted to OpenAPI `example` or `examples` field automatically with generated names (example1, example2...):
+
+```js
+fastify.route({
+  method: 'POST',
+  url: '/',
+  schema: {
+    querystring: {
+      type: 'object',
+      required: ['filter'],
+      properties: {
+        filter: {
+          type: 'object',
+          required: ['foo'],
+          properties: {
+            foo: { type: 'string' },
+            bar: { type: 'string' }
+          },
+          examples: [
+            { foo: 'bar', bar: 'baz' },
+            { foo: 'foo', bar: 'bar' }
+          ]
+        }
+      },
+      examples: [
+        { filter: { foo: 'bar', bar: 'baz' } }
+      ]
+    }
+  },
+  handler (request, reply) {
+    reply.send(request.query.filter)
+  }
+})
+```
+
+Will generate this in the OpenAPI v3 schema's `path`:
+
+```json
+"/": {
+  "post": {
+    "requestBody": {
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object",
+            "required": ["filter"],
+            "properties": {
+              "filter": {
+                "type": "object",
+                "required": ["foo"],
+                "properties": {
+                  "foo": { "type": "string" },
+                  "bar": { "type": "string" }
+                },
+                "example": { "foo": "bar", "bar": "baz" }
+              }
+            }
+          },
+          "examples": {
+            "example1": {
+              "value": { "filter": { "foo": "bar", "bar": "baz" } }
+            },
+            "example2": {
+              "value": { "filter": { "foo": "foo", "bar": "bar" } }
+            }
+          }
+        }
+      },
+      "required": true
+    },
+    "responses": { "200": { "description": "Default Response" } }
+  }
+}
+```
+
+If you want to set your own names or add descriptions to the examples of schemas, you can use `x-examples` field to set examples in [OpenAPI format](https://swagger.io/specification/#example-object):
+
+```js
+// Need to add a new allowed keyword to ajv in fastify instance
+const fastify = Fastify({
+  ajv: {
+    plugins: [
+      function (ajv) {
+        ajv.addKeyword({ keyword: 'x-examples' })
+      }
+    ]
+  }
+})
+
+fastify.route({
+  method: 'POST',
+  url: '/feed-animals',
+  schema: {
+    body: {
+      type: 'object',
+      required: ['animals'],
+      properties: {
+        animals: {
+          type: 'array',
+          items: {
+            type: 'string'
+          },
+          minItems: 1,
+        }
+      },
+      "x-examples": {
+        Cats: {
+          summary: "Feed cats",
+          description: 
+            "A longer **description** of the options with cats",
+          value: { 
+            animals: ["Tom", "Garfield", "Felix"] 
+          }
+        },
+        Dogs: {
+          summary: "Feed dogs",
+          value: { 
+            animals: ["Spike", "Odie", "Snoopy"] 
+          }
+        }
+      }
+    }
+  },
+  handler (request, reply) {
+    reply.send(request.body.animals)
+  }
+})
+```
+
 <a name="usage"></a>
 ## `$id` and `$ref` usage
 

lib/constants.js

@@ -2,8 +2,10 @@
 
 const xConsume = 'x-consume'
 const xResponseDescription = 'x-response-description'
+const xExamples = 'x-examples'
 
 module.exports = {
   xConsume,
-  xResponseDescription
+  xResponseDescription,
+  xExamples
 }

lib/spec/openapi/utils.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { readPackageJson, formatParamUrl, resolveLocalRef } = require('../../util/common')
-const { xResponseDescription, xConsume } = require('../../constants')
+const { xResponseDescription, xConsume, xExamples } = require('../../constants')
 const { rawRequired } = require('../../symbols')
 
 function prepareDefaultOptions (opts) {
@@ -136,26 +136,26 @@ function plainJsonObjectToOpenapi3 (container, jsonSchema, externalSchemas, secu
     case 'cookie':
     case 'query':
       toOpenapiProp = function (propertyName, jsonSchemaElement) {
-        const result = {
+        let result = {
           in: container,
           name: propertyName,
           required: jsonSchemaElement.required
         }
+
+        const media = schemaToMedia(jsonSchemaElement)
+
         // complex serialization in query or cookie, eg. JSON
         // https://swagger.io/docs/specification/describing-parameters/#schema-vs-content
         if (jsonSchemaElement[xConsume]) {
+          media.schema.required = jsonSchemaElement[rawRequired]
+
           result.content = {
-            [jsonSchemaElement[xConsume]]: {
-              schema: {
-                ...jsonSchemaElement,
-                required: jsonSchemaElement[rawRequired]
-              }
-            }
+            [jsonSchemaElement[xConsume]]: media
           }
 
           delete result.content[jsonSchemaElement[xConsume]].schema[xConsume]
         } else {
-          result.schema = jsonSchemaElement
+          result = { ...media, ...result }
         }
         // description should be optional
         if (jsonSchemaElement.description) result.description = jsonSchemaElement.description
@@ -167,20 +167,23 @@ function plainJsonObjectToOpenapi3 (container, jsonSchema, externalSchemas, secu
       break
     case 'path':
       toOpenapiProp = function (propertyName, jsonSchemaElement) {
+        const media = schemaToMedia(jsonSchemaElement)
+
         const result = {
+          ...media,
           in: container,
           name: propertyName,
-          required: true,
-          schema: jsonSchemaElement
+          required: true
         }
+
         // description should be optional
         if (jsonSchemaElement.description) result.description = jsonSchemaElement.description
         return result
       }
       break
     case 'header':
       toOpenapiProp = function (propertyName, jsonSchemaElement) {
-        return {
+        const result = {
           in: 'header',
           name: propertyName,
           required: jsonSchemaElement.required,
@@ -189,6 +192,17 @@ function plainJsonObjectToOpenapi3 (container, jsonSchema, externalSchemas, secu
             type: jsonSchemaElement.type
           }
         }
+
+        const media = schemaToMedia(jsonSchemaElement)
+        if (media.example) {
+          result.example = media.example
+        }
+
+        if (media.examples) {
+          result.examples = media.examples
+        }
+
+        return result
       }
       break
   }
@@ -207,28 +221,39 @@ function plainJsonObjectToOpenapi3 (container, jsonSchema, externalSchemas, secu
     })
 }
 
+function schemaToMedia (schema) {
+  const media = { schema }
+
+  if (schema.examples) {
+    media.examples = schema.examples
+
+    // examples is invalid property of media object schema
+    delete schema.examples
+  }
+
+  if (schema.example) {
+    media.example = schema.example
+  }
+
+  if (schema[xExamples]) {
+    media.examples = schema[xExamples]
+    delete schema[xExamples]
+  }
+
+  return media
+}
+
 function resolveBodyParams (body, schema, consumes, ref) {
   const resolved = transformDefsToComponents(ref.resolve(schema))
   if ((Array.isArray(consumes) && consumes.length === 0) || typeof consumes === 'undefined') {
     consumes = ['application/json']
   }
 
+  const media = schemaToMedia(resolved)
   consumes.forEach((consume) => {
-    // examples and example fields should be on the top level of the media object
-    const mediaObject = { schema: resolved }
-    if (resolved.examples) {
-      mediaObject.examples = resolved.examples
-
-      // examples is invalid property of media object schema
-      delete resolved.examples
-    }
-
-    if (resolved.example) {
-      mediaObject.example = resolved.example
-    }
-
-    body.content[consume] = mediaObject
+    body.content[consume] = media
   })
+
   if (resolved && resolved.required && resolved.required.length) {
     body.required = true
   }
@@ -305,10 +330,10 @@ function resolveResponse (fastifyResponseJson, produces, ref) {
       }
 
       delete resolved[xResponseDescription]
+
+      const media = schemaToMedia(resolved)
       produces.forEach((produce) => {
-        content[produce] = {
-          schema: resolved
-        }
+        content[produce] = media
       })
 
       response.content = content