How to Define Example Request Value in Microprofile4/OpenApi3 for POST Requests

Learn how to effectively define example request values in Microprofile4/OpenApi3 applications, specifically focused on POST request parameters.
---

Visit these links for original content and any more details, such as alternate solutions, latest updates/developments on topic, comments, revision history etc. For example, the original title of the Question was: Microprofile4/OpenApi3, how to define example request value?

If anything seems off to you, please feel free to write me at vlogize [AT] gmail [DOT] com.
---
Defining Example Request Values in Microprofile4/OpenApi3

When developing applications using Microprofile4 with OpenApi3, you may encounter the need to provide example request values for your POST request parameters. Including these examples can enhance the readability of your API documentation and assist developers in understanding the expected request format. This guide will guide you through the steps needed to accurately define example request values in your Java application.

The Problem: Missing Example in API Specification

In your Microprofile4 application built on Quarkus2, you may have attempted to provide an example for your POST request but found that it did not show up in the OpenApi specification. Let's break down what's happening.

Example Code without a Media Type

Here’s a simplified version of your original code that aims to define a request body but fails to display the example correctly:

[[See Video to Reveal this Text or Code Snippet]]

In this example, you provided a description and an example as a part of the @ RequestBody annotation. However, this did not result in the example being present in your OpenApi spec.

The Solution: Adding Media Type

The root of the issue is that you forgot to specify the mediaType in the Content. Including this piece of information correctly will ensure that your example shows up in the generated OpenApi documentation.

Updated Code Example

Let's modify your code by adding the mediaType to the Content annotation.

[[See Video to Reveal this Text or Code Snippet]]

Updated OpenApi Specification

After making this change, your OpenApi specification should now correctly reflect the inclusion of the example. The following structure illustrates the expected output:

[[See Video to Reveal this Text or Code Snippet]]

Conclusion

By including the mediaType in your Content annotation, you ensure that the example request value appears as intended in your OpenApi documentation for POST requests. This small adjustment can make a significant difference in API clarity and usability.

Continuing to enhance your API documentation with such details not only helps in the development process but also assists other developers who may use your API in the future. Thank you for reading, and happy coding with Microprofile4 and OpenApi3!