From a717abb8f78b7bdf1e743429ad9164e9e734b288 Mon Sep 17 00:00:00 2001 From: Fernando Castro Date: Tue, 10 Dec 2024 14:07:49 -0300 Subject: [PATCH 1/2] Create of the Custom examples param Add of a UnitTest to Validate --- .../configuration/ApiConfiguration.java | 4 + .../configuration/CommonApiConfiguration.java | 12 ++ .../configuration/parser/JsonParserUtils.java | 23 +++ .../io/github/kbuntrock/yaml/YamlWriter.java | 99 +++++++++++- .../github/kbuntrock/yaml/model/Content.java | 40 +++++ .../github/kbuntrock/yaml/model/Schema.java | 26 +++ .../kbuntrock/SpringClassAnalyserTest.java | 22 +++ .../resources/dto/example/ExampleEnum.java | 7 + .../dto/example/ExampleRequestBodyDto.java | 33 ++++ .../dto/example/ExampleResponseDto.java | 31 ++++ .../examples/TestExamplesController.java | 27 ++++ ...rTest.custom_examples_schema1.approved.txt | 150 ++++++++++++++++++ .../freeFields/custom_examples.txt | 52 ++++++ .../custom_examples_free_fields.txt | 47 ++++++ 14 files changed, 571 insertions(+), 2 deletions(-) create mode 100644 openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleEnum.java create mode 100644 openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleRequestBodyDto.java create mode 100644 openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleResponseDto.java create mode 100644 openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/endpoint/examples/TestExamplesController.java create mode 100644 openapi-maven-plugin/src/test/resources/io/github/kbuntrock/SpringClassAnalyserTest.custom_examples_schema1.approved.txt create mode 100644 openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples.txt create mode 100644 openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples_free_fields.txt diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/ApiConfiguration.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/ApiConfiguration.java index ee11b481..52c658a5 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/ApiConfiguration.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/ApiConfiguration.java @@ -88,6 +88,7 @@ public ApiConfiguration mergeWithCommonApiConfiguration(final CommonApiConfigura merged.extraSchemaClasses = copy.extraSchemaClasses; merged.customResponseTypeAnnotation = copy.customResponseTypeAnnotation; merged.defaultErrors = copy.defaultErrors; + merged.customExamples = copy.customExamples; merged.openapiModels = copy.openapiModels; merged.modelsAssociations = copy.modelsAssociations; merged.defaultNonNullableFields = copy.defaultNonNullableFields; @@ -166,6 +167,9 @@ public ApiConfiguration mergeWithCommonApiConfiguration(final CommonApiConfigura if(defaultErrors != null) { merged.setDefaultErrors(defaultErrors); } + if(customExamples != null) { + merged.setCustomExamples(customExamples); + } if(openapiModels != null) { merged.setOpenapiModels(openapiModels); } diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/CommonApiConfiguration.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/CommonApiConfiguration.java index faa194a7..0589d2d3 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/CommonApiConfiguration.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/CommonApiConfiguration.java @@ -102,6 +102,9 @@ public class CommonApiConfiguration { @Parameter protected String defaultErrors; + @Parameter + protected String customExamples; + @Parameter protected String openapiModels; @@ -129,6 +132,7 @@ public CommonApiConfiguration(final CommonApiConfiguration commonApiConfiguratio this.library = commonApiConfiguration.library; this.customResponseTypeAnnotation = commonApiConfiguration.customResponseTypeAnnotation; this.defaultErrors = commonApiConfiguration.defaultErrors; + this.customExamples = commonApiConfiguration.customExamples; this.openapiModels = commonApiConfiguration.openapiModels; this.modelsAssociations = commonApiConfiguration.modelsAssociations; this.defaultNonNullableFields = commonApiConfiguration.defaultNonNullableFields; @@ -352,6 +356,14 @@ public void setDefaultErrors(final String defaultErrors) { this.defaultErrors = defaultErrors; } + public String getCustomExamples() { + return customExamples; + } + + public void setCustomExamples(String customExamples) { + this.customExamples = customExamples; + } + public String getOpenapiModels() { return openapiModels; } diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java index e39164f0..4e74c1ce 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java @@ -73,4 +73,27 @@ public static void mergeInternal(final JsonNode mutatedNode, } } + public static JsonNode mergeJsonArray (JsonNode jsonArray){ + ObjectNode mergedNode = jsonObjectMapper.createObjectNode(); + if (jsonArray.isArray()) { + for (JsonNode jsonNode : jsonArray) { + if (jsonNode.isObject()) { + jsonNode.fields().forEachRemaining(entry -> { + String fieldName = entry.getKey(); + JsonNode fieldValue = entry.getValue(); + + // Adicionar ou substituir os valores no nó final + mergedNode.set(fieldName, fieldValue); + }); + } + } + } + return mergedNode; + } + public static JsonNode encapsulate (String name, JsonNode jsonArray){ + ObjectNode encapsulatedNode = jsonObjectMapper.createObjectNode(); + encapsulatedNode.put(name, jsonArray); + return encapsulatedNode; + } + } diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java index bb768185..633e1c7d 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java @@ -68,6 +68,10 @@ public class YamlWriter { private Optional freefields = Optional.empty(); private Map defaultErrors; + private Map parameterCustomExamples; + private Map schemaCustomExamples; + private Map requestBodycustomExamples; + private Map responseCustomExamples; public YamlWriter(final MavenProject mavenProject, final ApiConfiguration apiConfiguration) { this.apiConfiguration = apiConfiguration; @@ -121,6 +125,11 @@ public void write(final File file, final TagLibrary tagLibrary) throws IOExcepti iterator.forEachRemaining(entry -> defaultErrors.put(entry.getKey(), entry.getValue())); } + final Optional customExamplesNode = JsonParserUtils.parse( + CommonParserUtils.getContentFromFileOrText(mavenProject, apiConfiguration.getCustomExamples())); + + populateExamplesNodes(customExamplesNode); + final Specification specification = new Specification(); final Info info = new Info(mavenProject.getName(), mavenProject.getVersion(), freefields); specification.setInfo(info); @@ -259,7 +268,7 @@ private Map> createPaths(final TagLibrary tagLibr parameterElement.setIn(parameter.getLocation().toString().toLowerCase(Locale.ENGLISH)); parameterElement.setRequired(parameter.isRequired()); final Property schema = new Property(Content.fromDataObject(parameter).getSchema()); - + addExamplesInParameterIfExists(operation.getOperationId(),parameter.getName(), schema); // array in path parameters are not supported if(OpenApiDataType.ARRAY == parameter.getOpenApiResolvedType().getType() && ParameterLocation.PATH == parameter.getLocation()) { @@ -314,6 +323,7 @@ private Map> createPaths(final TagLibrary tagLibr final RequestBody requestBody = new RequestBody(); operation.setRequestBody(requestBody); final Content requestBodyContent = Content.fromDataObject(body); + addExamplesInBodyIfExists(operation.getOperationId(),requestBodyContent); if(body.getFormats() != null) { for(final String format : body.getFormats()) { requestBody.getContent().put(format, requestBodyContent); @@ -337,7 +347,6 @@ private Map> createPaths(final TagLibrary tagLibr "Parameter documentation found for endpoint body " + body.getName() + " ? " + parameterDoc.isPresent()); } - } // ------------------------- @@ -348,6 +357,7 @@ private Map> createPaths(final TagLibrary tagLibr response.setCode(endpoint.getResponseCode(), apiConfiguration.getDefaultSuccessfulOperationDescription()); if(endpoint.getResponseObject() != null) { final Content responseContent = Content.fromDataObject(endpoint.getResponseObject()); + addExamplesInResponseIfExists(operation.getOperationId(), responseContent); if(endpoint.getResponseFormats() != null) { for(final String format : endpoint.getResponseFormats()) { response.getContent().put(format, responseContent); @@ -408,6 +418,7 @@ private Map createSchemaSection(final TagLibrary library) { for(final DataObject dataObject : ordered) { final Set exploredSignatures = new HashSet<>(); final Schema schema = new Schema(dataObject, true, exploredSignatures, null, null); + addExamplesInSchemaIfExists(dataObject,schema); schemas.put(dataObject.getOpenApiResolvedType().isCompleteNode() ? dataObject.getOpenApiResolvedType().getModelName() : dataObject.getSchemaReferenceName(), schema); } @@ -419,5 +430,89 @@ private Map createSchemaSection(final TagLibrary library) { } return schemas; } + + private void populateExamplesNodes(Optional customExamplesNode) { + if(customExamplesNode.isPresent()) { + parameterCustomExamples = new LinkedHashMap<>(); + schemaCustomExamples = new LinkedHashMap<>(); + requestBodycustomExamples = new LinkedHashMap<>(); + responseCustomExamples = new LinkedHashMap<>(); + + JsonNode parameterNode = customExamplesNode.get().get("PARAMETER"); + JsonNode schemaNode = customExamplesNode.get().get("SCHEMA"); + JsonNode requestBodyNode = customExamplesNode.get().get("REQUESTBODY"); + JsonNode responseNode = customExamplesNode.get().get("RESPONSE"); + + if (parameterNode != null) { + final Iterator> iterator = parameterNode.fields(); + iterator.forEachRemaining(entry -> parameterCustomExamples.put(entry.getKey(), entry.getValue())); + } + + if (schemaNode != null) { + final Iterator> iterator = schemaNode.fields(); + iterator.forEachRemaining(entry -> schemaCustomExamples.put(entry.getKey(), entry.getValue())); + } + + if (requestBodyNode != null) { + final Iterator> iterator = requestBodyNode.fields(); + iterator.forEachRemaining(entry -> requestBodycustomExamples.put(entry.getKey(), entry.getValue())); + } + + if (responseNode != null) { + final Iterator> iterator = responseNode.fields(); + iterator.forEachRemaining(entry -> responseCustomExamples.put(entry.getKey(), entry.getValue())); + } + } + } + + private void addExamplesInParameterIfExists(String operationId, String name, Schema property) { + if (parameterCustomExamples!=null && property !=null){ + JsonNode operationNode = parameterCustomExamples.get(operationId); + if (operationNode != null) { + addExampleInSchema(operationNode.get(name), property); + } + } + } + private void addExamplesInSchemaIfExists(DataObject dataObject, Schema schema) { + if (schemaCustomExamples!=null && schema!=null){ + String simpleName = dataObject.getJavaClass().getSimpleName(); + addExampleInSchema(schemaCustomExamples.get(simpleName), schema); + } + } + + private void addExampleInSchema(JsonNode example, Schema property) { + if (example!=null) { + property.setExample(example); + } + } + + + + private void addExamplesInBodyIfExists(String operationId, Content requestBodyContent) { + addExampleInContent(requestBodycustomExamples, operationId, requestBodyContent); + } + + private void addExamplesInResponseIfExists(String operationId, Content responseBodyContent) { + addExampleInContent(responseCustomExamples, operationId, responseBodyContent); + } + + private void addExampleInContent(Map customExamples, String operationId, + Content content) { + if (customExamples != null) { + JsonNode example = customExamples.get(operationId); + if (example != null && content != null) { + if (example.isArray()) { + content.setExamples(JsonParserUtils.mergeJsonArray(example)); + } else { + if (example.get("$ref")!=null){ + content.setExamples(JsonParserUtils.encapsulate("ref", example)); + }else { + content.setExample(example); + } + } + } + } + } + } diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Content.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Content.java index a500d11d..eada95a9 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Content.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Content.java @@ -1,5 +1,7 @@ package io.github.kbuntrock.yaml.model; +import com.fasterxml.jackson.annotation.JsonAnyGetter; +import com.fasterxml.jackson.annotation.JsonIgnore; import io.github.kbuntrock.model.DataObject; import io.github.kbuntrock.model.ParameterObject; import io.github.kbuntrock.utils.OpenApiDataType; @@ -13,8 +15,14 @@ public class Content { + @JsonIgnore private Schema schema; + @JsonIgnore + protected Object example; + @JsonIgnore + protected Object examples; + public static Content fromDataObject(final ParameterObject parameterObject) { final Content content = fromDataObject((DataObject) parameterObject); @@ -55,4 +63,36 @@ public Schema getSchema() { return schema; } + public Object getExample() { + return example; + } + + public void setExample(Object example) { + this.example = example; + } + + public Object getExamples() { + return examples; + } + + public void setExamples(Object examples) { + this.examples = examples; + } + + @JsonAnyGetter + public Map getJsonObject() { + final Map map = new LinkedHashMap<>(); + if(schema != null) { + map.put("schema", schema); + } + if(example != null ) { + map.put("example", example); + } + if(examples != null ) { + map.put("examples", examples); + } + + return map; + } + } diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Schema.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Schema.java index 2d300c0b..d00030ca 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Schema.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/model/Schema.java @@ -57,6 +57,10 @@ public class Schema { @JsonIgnore protected Map properties; @JsonIgnore + protected Object example; + @JsonIgnore + protected Object examples; + @JsonIgnore protected List enumValues; @JsonIgnore protected List enumNames; @@ -364,6 +368,22 @@ public void setProperties(final Map properties) { this.properties = properties; } + public Object getExample() { + return example; + } + + public void setExample(Object example) { + this.example = example; + } + + public Object getExamples() { + return examples; + } + + public void setExamples(Object examples) { + this.examples = examples; + } + public List getEnumValues() { return enumValues; } @@ -456,6 +476,12 @@ public Map getJsonObject() { if(uniqueItems != null) { map.put("uniqueItems", uniqueItems); } + if(example != null ) { + map.put("example", example); + } + if(examples != null ) { + map.put("examples", examples); + } return map; } diff --git a/openapi-maven-plugin/src/test/java/io/github/kbuntrock/SpringClassAnalyserTest.java b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/SpringClassAnalyserTest.java index ae52defe..9c817a0c 100644 --- a/openapi-maven-plugin/src/test/java/io/github/kbuntrock/SpringClassAnalyserTest.java +++ b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/SpringClassAnalyserTest.java @@ -27,6 +27,7 @@ import io.github.kbuntrock.resources.endpoint.enumeration.TestEnumeration6Controller; import io.github.kbuntrock.resources.endpoint.enumeration.TestEnumeration7Controller; import io.github.kbuntrock.resources.endpoint.error.SameOperationController; +import io.github.kbuntrock.resources.endpoint.examples.TestExamplesController; import io.github.kbuntrock.resources.endpoint.file.FileUploadController; import io.github.kbuntrock.resources.endpoint.file.StreamResponseController; import io.github.kbuntrock.resources.endpoint.generic.ExtendsGenericObjectMap; @@ -82,12 +83,14 @@ import java.io.FileInputStream; import java.io.IOException; import java.io.InputStream; +import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.util.ArrayList; import java.util.Arrays; import java.util.Collections; import java.util.List; import java.util.Optional; +import org.apache.commons.io.IOUtils; import org.apache.maven.plugin.MojoExecutionException; import org.apache.maven.plugin.MojoFailureException; import org.apache.maven.project.MavenProject; @@ -944,6 +947,25 @@ public void nested_dtos() throws MojoFailureException, IOException, MojoExecutio checkGenerationResult(mojo.documentProject()); } + @Test + public void custom_examples_schema1() throws MojoFailureException, IOException, MojoExecutionException { + + final DocumentationMojo mojo = createBasicMojo(TestExamplesController.class.getCanonicalName()); + + ApiConfiguration apiConfiguration = mojo.getApis().get(0); + + final InputStream freeFieldsFileStream = this.getClass().getClassLoader() + .getResourceAsStream("ut/JavadocParserTest/freeFields/custom_examples_free_fields.txt"); + apiConfiguration.setFreeFields(IOUtils.toString(freeFieldsFileStream, StandardCharsets.UTF_8)); + + + final InputStream customExamplesFileStream = this.getClass().getClassLoader() + .getResourceAsStream("ut/JavadocParserTest/freeFields/custom_examples.txt"); + apiConfiguration.setCustomExamples(IOUtils.toString(customExamplesFileStream, StandardCharsets.UTF_8)); + + checkGenerationResult(mojo.documentProject()); + } + private ScanResult scanResult(Class clazz) { return new ClassGraph() diff --git a/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleEnum.java b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleEnum.java new file mode 100644 index 00000000..794a73d6 --- /dev/null +++ b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleEnum.java @@ -0,0 +1,7 @@ +package io.github.kbuntrock.resources.dto.example; + +public enum ExampleEnum { + EXAMPLE_A, + EXAMPLE_B, + EXAMPLE_C +} diff --git a/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleRequestBodyDto.java b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleRequestBodyDto.java new file mode 100644 index 00000000..3e9c9adb --- /dev/null +++ b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleRequestBodyDto.java @@ -0,0 +1,33 @@ +package io.github.kbuntrock.resources.dto.example; + +import java.util.List; + +public class ExampleRequestBodyDto { + private List requestEnumList; + private String requestName; + private String requestValue; + + public List getRequestEnumList() { + return requestEnumList; + } + + public void setRequestEnumList(List requestEnumList) { + this.requestEnumList = requestEnumList; + } + + public String getRequestName() { + return requestName; + } + + public void setRequestName(String requestName) { + this.requestName = requestName; + } + + public String getRequestValue() { + return requestValue; + } + + public void setRequestValue(String requestValue) { + this.requestValue = requestValue; + } +} diff --git a/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleResponseDto.java b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleResponseDto.java new file mode 100644 index 00000000..c7658737 --- /dev/null +++ b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/dto/example/ExampleResponseDto.java @@ -0,0 +1,31 @@ +package io.github.kbuntrock.resources.dto.example; + +public class ExampleResponseDto { + private ExampleEnum responseEnum; + private String responseName; + private String responseValue; + + public ExampleEnum getResponseEnum() { + return responseEnum; + } + + public void setResponseEnum(ExampleEnum responseEnum) { + this.responseEnum = responseEnum; + } + + public String getResponseName() { + return responseName; + } + + public void setResponseName(String responseName) { + this.responseName = responseName; + } + + public String getResponseValue() { + return responseValue; + } + + public void setResponseValue(String responseValue) { + this.responseValue = responseValue; + } +} diff --git a/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/endpoint/examples/TestExamplesController.java b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/endpoint/examples/TestExamplesController.java new file mode 100644 index 00000000..4e2621e8 --- /dev/null +++ b/openapi-maven-plugin/src/test/java/io/github/kbuntrock/resources/endpoint/examples/TestExamplesController.java @@ -0,0 +1,27 @@ +package io.github.kbuntrock.resources.endpoint.examples; + +import io.github.kbuntrock.resources.Constants; +import io.github.kbuntrock.resources.dto.EnumTest1Dto; +import io.github.kbuntrock.resources.dto.example.ExampleRequestBodyDto; +import io.github.kbuntrock.resources.dto.example.ExampleResponseDto; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestHeader; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RequestParam; + +@RequestMapping(Constants.BASE_API + "/test-examples-1") +public interface TestExamplesController { + + @PostMapping() + String postExample(@RequestBody ExampleRequestBodyDto exampleRequestBodyDto); + + @GetMapping("/{paramField}") + ExampleResponseDto getParameter(@PathVariable("paramField") String param, + @RequestHeader("headerField") String headerField); + + @GetMapping() + ExampleResponseDto getHeader(); +} diff --git a/openapi-maven-plugin/src/test/resources/io/github/kbuntrock/SpringClassAnalyserTest.custom_examples_schema1.approved.txt b/openapi-maven-plugin/src/test/resources/io/github/kbuntrock/SpringClassAnalyserTest.custom_examples_schema1.approved.txt new file mode 100644 index 00000000..71e6fbda --- /dev/null +++ b/openapi-maven-plugin/src/test/resources/io/github/kbuntrock/SpringClassAnalyserTest.custom_examples_schema1.approved.txt @@ -0,0 +1,150 @@ +--- +openapi: 3.0.3 +info: + title: This is a title + description: This is a sample server. + termsOfService: http://example.com/terms/ + contact: + name: API Support + url: http://www.example.com/support + email: support@example.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 10.5.36 +servers: + - url: https://development.test.com/v1 + description: Development server +tags: + - name: TestExamplesController +paths: + /api/test-examples-1: + get: + tags: + - TestExamplesController + operationId: getHeader + responses: + 200: + description: successful operation + content: + '*/*': + schema: + $ref: '#/components/schemas/ExampleResponseDto' + examples: + ref: + $ref: '#/components/examples/ResponseExample' + post: + tags: + - TestExamplesController + operationId: postExample + requestBody: + content: + '*/*': + schema: + $ref: '#/components/schemas/ExampleRequestBodyDto' + examples: + OPTION_A: + value: + requestEnumList: + - EXAMPLE_A + - EXAMPLE_A + requestName: example of a OPTION A Request Name + requestValue: example of a OPTION A Request Value + OPTION_B: + value: + requestEnumList: + - EXAMPLE_B + - EXAMPLE_B + requestName: example of a OPTION B Request Name + requestValue: example of a OPTION B Request Value + responses: + 200: + description: successful operation + content: + '*/*': + schema: + type: string + example: Example of a String value return + /api/test-examples-1/{paramField}: + get: + tags: + - TestExamplesController + operationId: getParameter + parameters: + - name: paramField + in: path + required: true + schema: + type: string + example: Path Variable Parameter Example + - name: headerField + in: header + required: true + schema: + type: string + example: Request Header Parameter Example + responses: + 200: + description: successful operation + content: + '*/*': + schema: + $ref: '#/components/schemas/ExampleResponseDto' + example: + responseEnum: EXAMPLE_C + responseName: example of a RESPONSE Response Name + responseValue: example of a RESPONSE Response Value +components: + schemas: + ExampleEnum: + type: string + enum: + - EXAMPLE_A + - EXAMPLE_B + - EXAMPLE_C + example: EXAMPLE_A + ExampleRequestBodyDto: + type: object + properties: + requestEnumList: + type: array + items: + $ref: '#/components/schemas/ExampleEnum' + requestName: + type: string + requestValue: + type: string + example: + requestEnumList: + - EXAMPLE_A + - EXAMPLE_C + requestName: example of a SCHEMA Request Name + requestValue: example of a SCHEMA Request Value + ExampleResponseDto: + type: object + properties: + responseEnum: + $ref: '#/components/schemas/ExampleEnum' + responseName: + type: string + responseValue: + type: string + example: + responseEnum: EXAMPLE_B + responseName: example of a SCHEMA Response Name + responseValue: example of a SCHEMA Response Value + securitySchemes: + jwt: + type: http + scheme: bearer + bearerFormat: JWT + examples: + ResponseExample: + responseEnum: EXAMPLE_C + responseName: example of a REFERENCE Response Name + responseValue: example of a REFERENCE Response Value +security: + - jwt: [] +externalDocs: + description: Find more info here + url: https://example.com diff --git a/openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples.txt b/openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples.txt new file mode 100644 index 00000000..69f65f69 --- /dev/null +++ b/openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples.txt @@ -0,0 +1,52 @@ +{ + "PARAMETER": { + "getParameter": { + "paramField": "Path Variable Parameter Example", + "headerField": "Request Header Parameter Example" + } + }, + "SCHEMA": { + "ExampleEnum": "EXAMPLE_A", + "ExampleRequestBodyDto": { + "requestEnumList": ["EXAMPLE_A","EXAMPLE_C"], + "requestName": "example of a SCHEMA Request Name", + "requestValue": "example of a SCHEMA Request Value" + }, + "ExampleResponseDto": { + "responseEnum": "EXAMPLE_B", + "responseName": "example of a SCHEMA Response Name", + "responseValue": "example of a SCHEMA Response Value" + } + }, + "REQUESTBODY": { + "postExample": [ + { + "OPTION_A":{ + "value": { + "requestEnumList": ["EXAMPLE_A","EXAMPLE_A"], + "requestName": "example of a OPTION A Request Name", + "requestValue": "example of a OPTION A Request Value" + } + }, + "OPTION_B":{ + "value": { + "requestEnumList": ["EXAMPLE_B","EXAMPLE_B"], + "requestName": "example of a OPTION B Request Name", + "requestValue": "example of a OPTION B Request Value" + } + } + } + ] + }, + "RESPONSE": { + "postExample": "Example of a String value return", + "getParameter": { + "responseEnum": "EXAMPLE_C", + "responseName": "example of a RESPONSE Response Name", + "responseValue": "example of a RESPONSE Response Value" + }, + "getHeader": { + "$ref": "#/components/examples/ResponseExample" + } + } +} \ No newline at end of file diff --git a/openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples_free_fields.txt b/openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples_free_fields.txt new file mode 100644 index 00000000..ebe59b78 --- /dev/null +++ b/openapi-maven-plugin/src/test/resources/ut/JavadocParserTest/freeFields/custom_examples_free_fields.txt @@ -0,0 +1,47 @@ +{ + "info": { + "title": "This is a title", + "description": "This is a sample server.", + "termsOfService": "http://example.com/terms/", + "contact": { + "name": "API Support", + "url": "http://www.example.com/support", + "email": "support@example.com" + }, + "license": { + "name": "Apache 2.0", + "url": "https://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "servers": [ + { + "url": "https://development.test.com/v1", + "description": "Development server" + } + ], + "security": [ + { + "jwt": [] + } + ], + "externalDocs": { + "description": "Find more info here", + "url": "https://example.com" + }, + "components": { + "examples": { + "ResponseExample": { + "responseEnum": "EXAMPLE_C", + "responseName": "example of a REFERENCE Response Name", + "responseValue": "example of a REFERENCE Response Value" + } + }, + "securitySchemes": { + "jwt": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT" + } + } + } +} \ No newline at end of file From 8c8b495a8a4f3373dc3741a84f36db8c93c57f40 Mon Sep 17 00:00:00 2001 From: Fernando Castro Date: Tue, 10 Dec 2024 15:45:07 -0300 Subject: [PATCH 2/2] Adjust the javaDoc --- .../kbuntrock/configuration/parser/JsonParserUtils.java | 8 ++++---- .../main/java/io/github/kbuntrock/yaml/YamlWriter.java | 1 + 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java index 4e74c1ce..44ee8108 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/configuration/parser/JsonParserUtils.java @@ -73,6 +73,7 @@ public static void mergeInternal(final JsonNode mutatedNode, } } + /**In the case that the Json Node is a Array and it's needed to merge all elements as a one object*/ public static JsonNode mergeJsonArray (JsonNode jsonArray){ ObjectNode mergedNode = jsonObjectMapper.createObjectNode(); if (jsonArray.isArray()) { @@ -81,8 +82,6 @@ public static JsonNode mergeJsonArray (JsonNode jsonArray){ jsonNode.fields().forEachRemaining(entry -> { String fieldName = entry.getKey(); JsonNode fieldValue = entry.getValue(); - - // Adicionar ou substituir os valores no nó final mergedNode.set(fieldName, fieldValue); }); } @@ -90,9 +89,10 @@ public static JsonNode mergeJsonArray (JsonNode jsonArray){ } return mergedNode; } - public static JsonNode encapsulate (String name, JsonNode jsonArray){ + /**Create a new Json Node and then add the jsonNode as a Child*/ + public static JsonNode encapsulate (String name, JsonNode jsonNode){ ObjectNode encapsulatedNode = jsonObjectMapper.createObjectNode(); - encapsulatedNode.put(name, jsonArray); + encapsulatedNode.put(name, jsonNode); return encapsulatedNode; } diff --git a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java index 633e1c7d..836ddc43 100644 --- a/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java +++ b/openapi-maven-plugin/src/main/java/io/github/kbuntrock/yaml/YamlWriter.java @@ -504,6 +504,7 @@ private void addExampleInContent(Map customExamples, String op if (example.isArray()) { content.setExamples(JsonParserUtils.mergeJsonArray(example)); } else { + /**In the OpenApi the $ref can only by used inside the examples tag, thus needing to have a inner object*/ if (example.get("$ref")!=null){ content.setExamples(JsonParserUtils.encapsulate("ref", example)); }else {