Support for api response examples has been added to Spring generator in #20933 - i.e. in OpenAPI Generator 7.13.0. As discussed in this PR, there are still some known limitations to the current implementation:
- Conversion of examples to strings can lead to uncompilable output due to improper escaping:
openapi: 3.0.3
info:
title: No examples in annotation example API
version: 1.0.0
paths:
/:
get:
summary: Create a dog
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
dog age negative:
$ref: '#/components/examples/DogAgeNegativeError'
components:
schemas:
Error:
type: object
properties:
message:
type: string
examples:
DogAgeNegativeError:
value:
message: '"' # <--- encoding problem here
- Only the
examples keyword is supported, but not the example (singular) keyword:
openapi: 3.0.3
info:
title: No examples in annotation example API
version: 1.0.0
paths:
/:
get:
summary: Create a dog
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example: # <--- not recognized
message: my description
components:
schemas:
Error:
type: object
properties:
message:
type: string
- specifying examples inside the component schemas isn't supported
openapi: 3.0.3
info:
title: No examples in annotation example API
version: 1.0.0
paths:
/:
get:
summary: Create a dog
responses:
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Error:
type: object
properties:
message:
type: string
example: # <--- not supported
message: my example string
- specifying examples in this alternative way shown in the spec results in empty names and no descriptions
Support for api response examples has been added to Spring generator in #20933 - i.e. in OpenAPI Generator 7.13.0. As discussed in this PR, there are still some known limitations to the current implementation:
exampleskeyword is supported, but not theexample(singular) keyword: