Skip to content

Commit bdfa6ea

Browse files
author
bnasslahsen
committed
API component schema description incorrectly overwritten by API parameter description. Fixes #852.
1 parent e5f058a commit bdfa6ea

File tree

11 files changed

+564
-1
lines changed

11 files changed

+564
-1
lines changed

‎springdoc-openapi-common/src/main/java/org/springdoc/core/GenericParameterBuilder.java

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,8 @@ private Schema calculateRequestBodySchema(Components components, ParameterInfo p
304304
if (schemaN.get$ref() != null && schemaN.get$ref().contains(AnnotationsUtils.COMPONENTS_REF)) {
305305
String key = schemaN.get$ref().substring(21);
306306
Schema existingSchema = components.getSchemas().get(key);
307-
existingSchema.setDescription(description);
307+
if (!StringUtils.isEmpty(description))
308+
existingSchema.setDescription(description);
308309
}
309310
else
310311
schemaN.setDescription(description);

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app131/HelloController.java

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
/*
2+
*
3+
* * Copyright 2019-2020 the original author or authors.
4+
* *
5+
* * Licensed under the Apache License, Version 2.0 (the "License");
6+
* * you may not use this file except in compliance with the License.
7+
* * You may obtain a copy of the License at
8+
* *
9+
* * https://www.apache.org/licenses/LICENSE-2.0
10+
* *
11+
* * Unless required by applicable law or agreed to in writing, software
12+
* * distributed under the License is distributed on an "AS IS" BASIS,
13+
* * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* * See the License for the specific language governing permissions and
15+
* * limitations under the License.
16+
*
17+
*/
18+
19+
package test.org.springdoc.api.app131;
20+
21+
import io.swagger.v3.oas.annotations.Operation;
22+
import io.swagger.v3.oas.annotations.Parameter;
23+
import io.swagger.v3.oas.annotations.media.Content;
24+
import io.swagger.v3.oas.annotations.media.Schema;
25+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
26+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
27+
28+
import org.springframework.http.HttpStatus;
29+
import org.springframework.web.bind.annotation.RequestBody;
30+
import org.springframework.web.bind.annotation.RequestMapping;
31+
import org.springframework.web.bind.annotation.RequestMethod;
32+
import org.springframework.web.bind.annotation.ResponseStatus;
33+
import org.springframework.web.bind.annotation.RestController;
34+
35+
@RestController
36+
public class HelloController<DataRequest> {
37+
38+
39+
@Operation(summary = "Create the organization", description = "Create the organization")
40+
@ApiResponses(
41+
value = {
42+
@ApiResponse(
43+
responseCode = "204",
44+
description = "The organization was created successfully"),
45+
@ApiResponse(
46+
responseCode = "400",
47+
description = "Invalid argument",
48+
content =
49+
@Content(
50+
mediaType = "application/json",
51+
schema = @Schema(implementation = RestControllerError.class))),
52+
@ApiResponse(
53+
responseCode = "409",
54+
description = "An organization with the specified ID already exists",
55+
content =
56+
@Content(
57+
mediaType = "application/json",
58+
schema = @Schema(implementation = RestControllerError.class))),
59+
@ApiResponse(
60+
responseCode = "500",
61+
description =
62+
"An error has occurred and the request could not be processed at this time",
63+
content =
64+
@Content(
65+
mediaType = "application/json",
66+
schema = @Schema(implementation = RestControllerError.class)))
67+
})
68+
@RequestMapping(
69+
value = "/organizations",
70+
method = RequestMethod.POST,
71+
produces = "application/json")
72+
@ResponseStatus(HttpStatus.NO_CONTENT)
73+
public void createOrganization(
74+
@Parameter(name = "organization", required = true)
75+
@RequestBody
76+
Organization organization) {
77+
78+
79+
}
80+
81+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app131/Organization.java

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package test.org.springdoc.api.app131;
2+
3+
4+
import java.util.UUID;
5+
6+
import com.fasterxml.jackson.annotation.JsonInclude;
7+
import com.fasterxml.jackson.annotation.JsonProperty;
8+
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
9+
import io.swagger.v3.oas.annotations.media.Schema;
10+
11+
@Schema(description =
12+
"This is the description being overwritten")
13+
@JsonInclude(JsonInclude.Include.NON_NULL)
14+
@JsonPropertyOrder({"id", "name"})
15+
public class Organization {
16+
17+
@Schema(
18+
description =
19+
"The Universally Unique Identifier (UUID) uniquely identifying the organization",
20+
required = true)
21+
@JsonProperty(required = true)
22+
private UUID id;
23+
24+
@Schema(description = "The name of the organization", required = true)
25+
@JsonProperty(required = true)
26+
private String name;
27+
28+
public Organization() {}
29+
30+
public UUID getId() {
31+
return id;
32+
}
33+
34+
public String getName() {
35+
return name;
36+
}
37+
38+
public void setId(UUID id) {
39+
this.id = id;
40+
}
41+
42+
public void setName(String name) {
43+
this.name = name;
44+
}
45+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app131/RestControllerError.java

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package test.org.springdoc.api.app131;
2+
3+
import com.fasterxml.jackson.annotation.JsonProperty;
4+
5+
public class RestControllerError {
6+
7+
@JsonProperty
8+
private String id;
9+
10+
@JsonProperty
11+
private String message;
12+
13+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app131/SpringDocApp131Test.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
*
3+
* *
4+
* * *
5+
* * * * Copyright 2019-2020 the original author or authors.
6+
* * * *
7+
* * * * Licensed under the Apache License, Version 2.0 (the "License");
8+
* * * * you may not use this file except in compliance with the License.
9+
* * * * You may obtain a copy of the License at
10+
* * * *
11+
* * * * https://www.apache.org/licenses/LICENSE-2.0
12+
* * * *
13+
* * * * Unless required by applicable law or agreed to in writing, software
14+
* * * * distributed under the License is distributed on an "AS IS" BASIS,
15+
* * * * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* * * * See the License for the specific language governing permissions and
17+
* * * * limitations under the License.
18+
* * *
19+
* *
20+
*
21+
*
22+
*/
23+
package test.org.springdoc.api.app131;
24+
25+
import test.org.springdoc.api.AbstractSpringDocTest;
26+
27+
import org.springframework.boot.autoconfigure.SpringBootApplication;
28+
29+
30+
/**
31+
* Tests Spring meta-annotations as method parameters
32+
*/
33+
public class SpringDocApp131Test extends AbstractSpringDocTest {
34+
35+
@SpringBootApplication
36+
static class SpringDocTestApp {}
37+
38+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app132/HelloController.java

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
/*
2+
*
3+
* * Copyright 2019-2020 the original author or authors.
4+
* *
5+
* * Licensed under the Apache License, Version 2.0 (the "License");
6+
* * you may not use this file except in compliance with the License.
7+
* * You may obtain a copy of the License at
8+
* *
9+
* * https://www.apache.org/licenses/LICENSE-2.0
10+
* *
11+
* * Unless required by applicable law or agreed to in writing, software
12+
* * distributed under the License is distributed on an "AS IS" BASIS,
13+
* * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* * See the License for the specific language governing permissions and
15+
* * limitations under the License.
16+
*
17+
*/
18+
19+
package test.org.springdoc.api.app132;
20+
21+
import io.swagger.v3.oas.annotations.Operation;
22+
import io.swagger.v3.oas.annotations.Parameter;
23+
import io.swagger.v3.oas.annotations.media.Content;
24+
import io.swagger.v3.oas.annotations.media.Schema;
25+
import io.swagger.v3.oas.annotations.responses.ApiResponse;
26+
import io.swagger.v3.oas.annotations.responses.ApiResponses;
27+
28+
import org.springframework.http.HttpStatus;
29+
import org.springframework.web.bind.annotation.RequestBody;
30+
import org.springframework.web.bind.annotation.RequestMapping;
31+
import org.springframework.web.bind.annotation.RequestMethod;
32+
import org.springframework.web.bind.annotation.ResponseStatus;
33+
import org.springframework.web.bind.annotation.RestController;
34+
35+
@RestController
36+
public class HelloController<DataRequest> {
37+
38+
39+
@Operation(summary = "Create the organization", description = "Create the organization")
40+
@ApiResponses(
41+
value = {
42+
@ApiResponse(
43+
responseCode = "204",
44+
description = "The organization was created successfully"),
45+
@ApiResponse(
46+
responseCode = "400",
47+
description = "Invalid argument",
48+
content =
49+
@Content(
50+
mediaType = "application/json",
51+
schema = @Schema(implementation = RestControllerError.class))),
52+
@ApiResponse(
53+
responseCode = "409",
54+
description = "An organization with the specified ID already exists",
55+
content =
56+
@Content(
57+
mediaType = "application/json",
58+
schema = @Schema(implementation = RestControllerError.class))),
59+
@ApiResponse(
60+
responseCode = "500",
61+
description =
62+
"An error has occurred and the request could not be processed at this time",
63+
content =
64+
@Content(
65+
mediaType = "application/json",
66+
schema = @Schema(implementation = RestControllerError.class)))
67+
})
68+
@RequestMapping(
69+
value = "/organizations",
70+
method = RequestMethod.POST,
71+
produces = "application/json")
72+
@ResponseStatus(HttpStatus.NO_CONTENT)
73+
public void createOrganization(
74+
@Parameter(name = "organization", description = "i want to override the description of this object", required = true)
75+
@RequestBody
76+
Organization organization) {
77+
78+
79+
}
80+
81+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app132/Organization.java

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package test.org.springdoc.api.app132;
2+
3+
4+
import java.util.UUID;
5+
6+
import com.fasterxml.jackson.annotation.JsonInclude;
7+
import com.fasterxml.jackson.annotation.JsonProperty;
8+
import com.fasterxml.jackson.annotation.JsonPropertyOrder;
9+
import io.swagger.v3.oas.annotations.media.Schema;
10+
11+
@Schema(description =
12+
"This is the description being overwritten")
13+
@JsonInclude(JsonInclude.Include.NON_NULL)
14+
@JsonPropertyOrder({"id", "name"})
15+
public class Organization {
16+
17+
@Schema(
18+
description =
19+
"The Universally Unique Identifier (UUID) uniquely identifying the organization",
20+
required = true)
21+
@JsonProperty(required = true)
22+
private UUID id;
23+
24+
@Schema(description = "The name of the organization", required = true)
25+
@JsonProperty(required = true)
26+
private String name;
27+
28+
public Organization() {}
29+
30+
public UUID getId() {
31+
return id;
32+
}
33+
34+
public String getName() {
35+
return name;
36+
}
37+
38+
public void setId(UUID id) {
39+
this.id = id;
40+
}
41+
42+
public void setName(String name) {
43+
this.name = name;
44+
}
45+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app132/RestControllerError.java

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
package test.org.springdoc.api.app132;
2+
3+
import com.fasterxml.jackson.annotation.JsonProperty;
4+
5+
public class RestControllerError {
6+
7+
@JsonProperty
8+
private String id;
9+
10+
@JsonProperty
11+
private String message;
12+
13+
}

‎springdoc-openapi-webmvc-core/src/test/java/test/org/springdoc/api/app132/SpringDocApp132Test.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
*
3+
* *
4+
* * *
5+
* * * * Copyright 2019-2020 the original author or authors.
6+
* * * *
7+
* * * * Licensed under the Apache License, Version 2.0 (the "License");
8+
* * * * you may not use this file except in compliance with the License.
9+
* * * * You may obtain a copy of the License at
10+
* * * *
11+
* * * * https://www.apache.org/licenses/LICENSE-2.0
12+
* * * *
13+
* * * * Unless required by applicable law or agreed to in writing, software
14+
* * * * distributed under the License is distributed on an "AS IS" BASIS,
15+
* * * * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* * * * See the License for the specific language governing permissions and
17+
* * * * limitations under the License.
18+
* * *
19+
* *
20+
*
21+
*
22+
*/
23+
package test.org.springdoc.api.app132;
24+
25+
import test.org.springdoc.api.AbstractSpringDocTest;
26+
27+
import org.springframework.boot.autoconfigure.SpringBootApplication;
28+
29+
30+
/**
31+
* Tests Spring meta-annotations as method parameters
32+
*/
33+
public class SpringDocApp132Test extends AbstractSpringDocTest {
34+
35+
@SpringBootApplication
36+
static class SpringDocTestApp {}
37+
38+
}

0 commit comments

Comments
 (0)