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

lfec · 2024-12-10T20:27:05Z

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

Add the new configuration to the Maven pom.xml:

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

Create the external file using the prescribed JSON structure.
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

Add of a UnitTest to Validate

kbuntrock · 2024-12-13T17:28:58Z

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.

# Conflicts: # openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java # openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Content.java # openapi-maven-plugin/src/test/java/io/github/kbuntrock/SpringClassAnalyserTest.java

kbuntrock

First of all, thank you very much @lfec for your tremendous patience!

I read your PR, looks pretty good to me. A big shout out for this work!

I have a few remarks about it. I have posted them with the code when it was appropriate, and I post here the more global remarks:

PARAMETER, REQUESTBODY and RESPONSE use the operationId as the key. Therefore, it looks more straightforward to me to organise it around the operationId key.
Request body and response can differ regarding the content-type. I would like to introduce a new hierarchic level and the "default" keyword for examples which should be applied for all content-types.
The array for multiple example options seems unused since you use only the first element and then put a map in it (OPTION_A, OPTION_B). I suggest to remove the array and apply a different treatment if the node contains a single element or not.
-> if single node : declaring an "example" node, and the name of the example is not used in the specification
-> if multiple : declaring an "examples" node, the names of the examples are kept
Parameters seems also to offer multiple examples, we should support this.

So, regarding to the 3 first points, here is an example of the new structure I suggest:

{
  "OPERATIONS" : [
	"operationId_1" : {
	  "PARAMETER": {
	    "first_parameter_name" {
		  "example_name": { // Here the name of the example will not be used in the documentation since it is alone
		  
		  }
		},
		"second_parameter_name" {
		  "example_name_1": {
		  
		  },
		  "example_name_2": {
		  
		  },
		}
	  },
	  "REQUESTBODY": {
	    "default": {
		  "example_name": { // Here the name of the example will not be used in the documentation since it is alone
		  
		  }
		}
	  },
	  "RESPONSE": {
		"application/json": {
		  "example_name": { // Here the name of the example will not be used in the documentation since it is alone
		  
		  }
		},
		"application/xml": {
		  "example_name_1": {
		  
		  },
		  "example_name_2": {
		  
		  }
		}
	  }
	},
	"operationId_2" : {
	  "PARAMETER": {},
	  "REQUESTBODY": {},
	  "RESPONSE": {}
	}
  ],
  "SCHEMA": {}
}

Regarding the 4th point, I suggest to change the positioning of the example outside the parameters schema in order to switch more easily between a mono/multiple examples.

Which would lead to this kind of generated doc snippet:

parameters:
  - name: paramField
    in: path
    required: true
    schema:
      type: string
    examples: 
      example1:
        value: value example one
      example2: 
        value: value example two
  - name: headerField
    in: header
    required: true
    schema:
      type: string
    example: header example value

So what do you think about these suggestions? :)

kbuntrock · 2025-05-15T12:14:50Z

...en-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples_free_fields.txt

+  },
+  "components": {
+    "examples": {
+      "ResponseExample": {


Small change in order to make it a valid example regarding the specification:

Suggested change

"ResponseExample": {

"ResponseExample": {

"value": {

"responseEnum": "EXAMPLE_C",

"responseName": "example of a REFERENCE Response Name",

"responseValue": "example of a REFERENCE Response Value"

}

}

Current warning (not reported in the plugin) is :
This is not a valid example object : "Structural error at components.examples.ResponseExample should NOT have additional properties additionalProperty: responseEnum, responseName, responseValue"

kbuntrock · 2025-05-15T12:17:35Z

openapi-maven-plugin/pom.xml

@@ -7,7 +7,7 @@

  <groupId>io.github.kbuntrock</groupId>
  <artifactId>openapi-maven-plugin</artifactId>
-  <version>0.0.24-SNAPSHOT</version>
+  <version>0.0.22-EXAMPLES</version>


Please discard this change when you are ready for a merge - in order to fix the integration tests.

kbuntrock · 2025-05-15T12:19:31Z

...api-maven-plugin/src/main/java/io/github/kbuntrock/configuration/CommonApiConfiguration.java

@@ -102,6 +102,9 @@ public class CommonApiConfiguration {
 	@Parameter
 	protected String defaultErrors;

+	@Parameter
+	protected String customExamples;


Better to put a list here, so people can split / organise their examples in multiple files.

And for the merge feature in the ApiConfiguration with a list, just replace the list, there is no need for too much sophistication.

kbuntrock · 2025-05-15T12:24:04Z

openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java

@@ -130,6 +134,11 @@ public void write(final File file, final TagLibrary tagLibrary) throws IOExcepti
 			iterator.forEachRemaining(entry -> defaultErrors.put(entry.getKey(), entry.getValue()));
 		}

+		final Optional<JsonNode> customExamplesNode = JsonParserUtils.parse(
+			CommonParserUtils.getContentFromFileOrText(mavenProject, apiConfiguration.getCustomExamples()));


Idea for a next iteration: allowing folders in example configuration. If so, we'll parse every files in it.

kbuntrock · 2025-05-15T13:14:13Z

openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java

+			requestBodycustomExamples = new LinkedHashMap<>();
+			responseCustomExamples = new LinkedHashMap<>();
+
+			JsonNode parameterNode = customExamplesNode.get().get("PARAMETER");


Since there is no other "all caps" convention in this project, I would prefer if we use lowercase or accept both lowercase and uppercase.

lfec added 2 commits December 10, 2024 14:07

Create of the Custom examples param

a717abb

Add of a UnitTest to Validate

Adjust the javaDoc

8c8b495

lfec added 2 commits May 9, 2025 15:18

Upmerge

6c1da21

kbuntrock requested changes May 15, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

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

Uh oh!

lfec commented Dec 10, 2024 •

edited

Loading

Uh oh!

kbuntrock commented Dec 13, 2024

Uh oh!

kbuntrock left a comment •

edited

Loading

Uh oh!

kbuntrock May 15, 2025

Uh oh!

kbuntrock May 15, 2025

Uh oh!

kbuntrock May 15, 2025

Uh oh!

kbuntrock May 15, 2025

Uh oh!

kbuntrock May 15, 2025

Uh oh!

Uh oh!

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

lfec commented Dec 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Description

Key Features:

How to Use

Example

1. Parameter Examples

2. Schema Examples

3. Request Body Examples

4. Response Examples

Uh oh!

kbuntrock commented Dec 13, 2024

Uh oh!

kbuntrock left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kbuntrock May 15, 2025

Choose a reason for hiding this comment

Uh oh!

kbuntrock May 15, 2025

Choose a reason for hiding this comment

Uh oh!

kbuntrock May 15, 2025

Choose a reason for hiding this comment

Uh oh!

kbuntrock May 15, 2025

Choose a reason for hiding this comment

Uh oh!

kbuntrock May 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lfec commented Dec 10, 2024 •

edited

Loading

kbuntrock left a comment •

edited

Loading