swagger-api / swagger-api/swagger-core

@ExampleObject description attribute not empty

Open
#4,448 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog
Dominant language
Java
Stars
7.5k
Forks
2.3k
Avg merge
18h 1m
Merged PRs (30d)
10

Description

I'm facing this issue that also if the description attribute for the @ExampleObject (doc) annotation is empty, in the swagger online editor it is show, and it takes the name of the example.

Here my code

@ApiResponse(
	responseCode = "200", 
	description = "Book found", 
	content = { 
		@Content(
			mediaType = "application/json", 
			schema = @Schema(implementation = Book.class),
			examples = {
				@ExampleObject(
					name = "example 1", 
					value = "{\"id\": \"1\", \"title\":\"The Fellowship of the Ring\", \"author\": \"J.R.R. Tolkien\", \"publisher\": \"Allen & Unwin\"}"),
				@ExampleObject(
					name = "example 2",
					description = "",
					value = "{\"id\": \"1\", \"title\":\"The Fellowship of the Ring\", \"author\": \"J.R.R. Tolkien\", \"publisher\": null}")})

As you can see the description is not set for the example 1, so I'm expecting the default value (""), and is set to an empty string in the example 2.

Here the result in the swagger online editor for example 1
image

Also for the example 2
image

The editor will show me always the description, but I do not need it. What do I have to do?

I'm using:

  1. Java 8
  2. Spring Boot 2.7.16
  3. springdoc-openapi-ui 1.7.0

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No repository file or test is named in the issue. Reproduce the annotation example with the stated Java, Spring Boot, and springdoc versions, then inspect the generated OpenAPI output and the relevant annotation-processing entry point. Done means an unset or empty ExampleObject description is omitted rather than displayed as the example name.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, openapi, spring-boot
Domain
api, backend-api-design
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.