Issue-79 - To be able to Add Examples for Parameters, Schemas ans Request

[lfec]

Add Support for External Example Configuration in openapi-maven-plugin

Description

This Pull Request introduces the ability to add Examples to OpenAPI entities, parameters, and operations. The examples can be specified via an external file provided in the Maven plugin configuration. This feature enhances the plugin by allowing developers to maintain and manage examples separately from the codebase.
This is also mentioned in #79 and #50

Key Features:

• New Configuration Option:

  • A new configuration parameter has been added to the Maven pom.xml, allowing the user to specify the path to an external file containing examples.

• Supported Example Structure:

  • The external file should follow the JSON structure below:

    {
      "PARAMETER": {},
      "SCHEMA": {},
      "REQUESTBODY": {},
      "RESPONSE": {}
    }

  • SCHEMA: Uses entity names as keys to assign examples.
  • PARAMETER, REQUESTBODY, RESPONSE: Use the operationId as the key to define examples.

• Code First Approach: This feature aligns with the plugin's philosophy of maintaining documentation through code-first principles, while offering flexibility for managing external examples.

How to Use

1. Add the new configuration to the Maven pom.xml:

   <configuration>
       <customExamples>src\main\webapp\openapi\examples.json</customExamples>
   </configuration>
   

2. Create the external file using the prescribed JSON structure.
3. Run the Maven goal as usual, and the plugin will automatically incorporate the examples into the generated OpenAPI schema.

Example

Below are examples of how the configuration can be used for each module: PARAMETER, SCHEMA, REQUESTBODY, and RESPONSE.

---

1. Parameter Examples

The example below demonstrates how this configuration supports both Path parameters and Header parameters:

  {
    "PARAMETER": {
      "getParameter": {
        "paramField": "Path Variable Parameter Example",
        "headerField": "Request Header Parameter Example"
      }
    }
  }

2. Schema Examples

In this configuration, ExampleEnum and ExampleRequestBodyDto represent the names of entities. This demonstrates that the feature works for both simple entities (e.g., enums) and complex objects (e.g., DTOs with nested properties)

  {
    "SCHEMA": {
      "ExampleEnum": "EXAMPLE_A",
      "ExampleRequestBodyDto": {
        "requestEnumList": ["EXAMPLE_A", "EXAMPLE_C"],
        "requestName": "example of a SCHEMA Request Name",
        "requestValue": "example of a SCHEMA Request Value"
      }
    }
  }

3. Request Body Examples

For the REQUESTBODY module, the configuration allows both a default example and multiple options that OpenAPI supports. When using multiple options, the JSON should be formatted as an array to allow readers to choose during testing

  {
    "REQUESTBODY": {
      "postExample": [
        {
          "OPTION_A": {
            "value": {
              "requestEnumList": ["EXAMPLE_A", "EXAMPLE_A"],
              "requestName": "example of an OPTION A Request Name",
              "requestValue": "example of an OPTION A Request Value"
            }
          },
          "OPTION_B": {
            "value": {
              "requestEnumList": ["EXAMPLE_B", "EXAMPLE_B"],
              "requestName": "example of an OPTION B Request Name",
              "requestValue": "example of an OPTION B Request Value"
            }
          }
        }
      ]
    }
  }

4. Response Examples

The following example demonstrates how to configure RESPONSE examples.

  {
    "RESPONSE": {
      "postExample": "Example of a String value return",
      "getParameter": {
        "responseEnum": "EXAMPLE_C",
        "responseName": "example of a RESPONSE Response Name",
        "responseValue": "example of a RESPONSE Response Value"
      },
      "getHeader": {
        "$ref": "#/components/examples/ResponseExample"
      }
    }
  }

BOTH Request Body and Response supports Multi Options and referenced examples

To use the $ref the respective information must be informed using Free Fields

[kbuntrock]

Thank you very much @lfec for this huge PR. I greatly appreciate the detailed explanations about this new feature.
I'll have a closer look at it this weekend.