[Proposal] OpenAPI Example Annotation #6730
Labels
Area/BallerinaToOpenapi
module/openapi-tools
Status/Implemented
Implemented proposals
Type/NewFeature
Type/Proposal
Milestone
Summary
This proposal aims to introduce example annotations in the OpenAPI tool. This feature will enable rendering example schemas in the generated OpenAPI specification.
Goals
Non-Goals
External Examples
in Adding Examples) for a example valueMotivation
The OpenAPI specification allows adding examples to parameters, properties and objects. These examples can be read by the tools and the libraries that process the OpenAPI specification. For example, the Ballerina OpenAPI tool can use the examples to generate the mock client or server.
Description
Proposed design
The examples can be specified in the following two ways in the OpenAPI specification:
The
example
schema, which represents a single exampleThe
examples
schema, which represents multiple examples with distinct key valuesThe above scenarios will be addressed via two different annotations in the Ballerina OpenAPI tool:
The
@openapi:Example
annotationThe
@openapi:Examples
annotationThe
example
andexamples
schemas can be specified in objects, individual properties and operation parameters. This is supported by enabling the ballerina annotation on the Ballerina types, record fields and resource function parameter.The types can be imported from external ballerina packages and the examples from these annotations should be accessed in the compiler plugin. For that requirement, the annotations are designed as constant annotations.
The proposed annotation definitions look like this:
The examples schemas will be added as follows:
media-type
field of the request bodyCompiler validation
@openapi:Example
/@openapi:Examples
on the same parameterExamples
Parameter example:
Ballerina representation:
Generated Schema:
Request body example with inline object schema:
Ballerina representation:
Generated Schema:
Request body example with reference:
Ballerina representation:
Generated Schema:
Property level example:
Ballerina representation:
Generated Schema:
Object level example:
Ballerina representation:
Generated Schema:
Array example:
Ballerina representation:
Generated Schema:
References
Future Works
Provide a way to add a file path or external link for a example value:
This can be done by adding a union type for the annotation type. This has to be checked with the Ballerina lang team:
Provide a way to automatically generate example and add it in the example annotation:
When the type is complex, it is not practical to add an example manually. So it will be better to generate a sample example using a code action or generate one with Ballerina AI tool.
In addition to that, Ballerina tooling supports creating records from JSON examples. We could use that to automatically inject the example annotation when a record is created from JSON.
The text was updated successfully, but these errors were encountered: