From 5bda347bc3e8843b694c795bdc72e02d6f8b8f4f Mon Sep 17 00:00:00 2001 From: Tomasz Wrobel Date: Mon, 26 Apr 2021 11:28:57 +0200 Subject: Align swagger documentation -Add examples in request parameters -Add example responses Issue-ID: SDC-3185 Signed-off-by: Tomasz Wrobel Change-Id: Ib3896d48297c4808e252c8715b380bf6e37d8003 --- OpenAPI.yaml | 108 +++++++++++---------- .../helmvalidator/api/ValidationController.java | 29 ++++-- .../helmvalidator/config/DocsConfiguration.java | 62 ------------ .../sdc/helmvalidator/config/LoggerConfig.java | 2 + .../config/docs/DocsConfiguration.java | 107 ++++++++++++++++++++ .../config/docs/ValidationRequestParameters.java | 78 +++++++++++++++ .../sdc/helmvalidator/config/LoggerConfigTest.java | 2 + 7 files changed, 270 insertions(+), 118 deletions(-) delete mode 100644 src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java create mode 100644 src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java create mode 100644 src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java diff --git a/OpenAPI.yaml b/OpenAPI.yaml index 686d3e6..69a6de8 100644 --- a/OpenAPI.yaml +++ b/OpenAPI.yaml @@ -4,70 +4,49 @@ info: description: Application for validating Helm charts. version: v0 servers: - - url: 'http://localhost:8080' + - url: http://localhost:8080 description: Generated server url tags: - name: Actuator description: Monitor and interact externalDocs: description: Spring Boot Actuator Web API Documentation - url: 'https://docs.spring.io/spring-boot/docs/current/actuator-api/html/' + url: https://docs.spring.io/spring-boot/docs/current/actuator-api/html/ paths: /validate: post: tags: - ValidationService summary: Validate chart - description: Web endpoint for Helm charts validation. + description: Web endpoint for Helm charts validation. Helm chart in .tgz format + is required. operationId: validate - parameters: - - name: versionDesired - in: query - description: Desired Helm version which should be used to validate the chart - required: false - schema: - type: string - - name: isLinted - in: query - description: 'If false, there will be an attempt to render the chart without linting it first' - required: false - schema: - type: boolean - default: false - - name: isStrictLinted - in: query - description: Linting should be strict or not - required: false - schema: - type: boolean - default: false requestBody: content: multipart/form-data: schema: - required: - - file - type: object - properties: - file: - type: string - description: Helm chart that should be validated (packed in .tgz format) - format: binary + $ref: '#/components/schemas/ValidationRequestParameters' + required: true responses: - '200': - description: Helm chart successfully validated + "500": + description: Something went wrong during validation execution content: application/json: schema: - $ref: '#/components/schemas/ValidationResult' - '400': - description: Chart cannot be validated using selected version + $ref: '#/components/schemas/ValidationErrorResponse' + "200": + description: Helm chart successfully validated content: application/json: schema: - $ref: '#/components/schemas/ValidationErrorResponse' - '500': - description: Something went wrong during validation execution + $ref: '#/components/schemas/ValidationResult' + examples: + Simple Validation: + $ref: '#/components/examples/simpleValidation' + Lint Validation: + $ref: '#/components/examples/validationWithLint' + "400": + description: Chart cannot be validated using selected version content: application/json: schema: @@ -80,18 +59,18 @@ paths: description: Web endpoint for showing supported Helm versions. operationId: supportedVersions responses: - '200': - description: Supported Helm versions successfully returned + "500": + description: Something went wrong during getting Helm versions content: '*/*': schema: - $ref: '#/components/schemas/VersionsResponse' - '500': - description: Something went wrong during getting Helm versions + $ref: '#/components/schemas/ValidationErrorResponse' + "200": + description: Supported Helm versions successfully returned content: '*/*': schema: - $ref: '#/components/schemas/ValidationErrorResponse' + $ref: '#/components/schemas/VersionsResponse' /actuator: get: tags: @@ -99,7 +78,7 @@ paths: summary: Actuator root web endpoint operationId: links_0 responses: - '200': + "200": description: OK content: '*/*': @@ -116,7 +95,7 @@ paths: summary: Actuator web endpoint 'info' operationId: handle_1 responses: - '200': + "200": description: OK content: '*/*': @@ -129,7 +108,7 @@ paths: summary: Actuator web endpoint 'health' operationId: handle_2 responses: - '200': + "200": description: OK content: '*/*': @@ -142,7 +121,7 @@ paths: summary: Actuator web endpoint 'health-path' operationId: handle_3 responses: - '200': + "200": description: OK content: '*/*': @@ -156,6 +135,27 @@ components: type: array items: type: string + ValidationRequestParameters: + required: + - file + type: object + properties: + versionDesired: + type: string + description: "Desired Helm version which should be used to validate the\ + \ chart. If parameter is not provided validation is processing with version\ + \ based on chart's apiVersion. Version could be provided in 'semantic\ + \ version' or 'major version'.
Allowed formats:
- Semantic version\ + \ [X.Y.Z] e.g. 3.5.2
- Major version [vX] e.g. v3" + file: + type: string + format: binary + isLinted: + type: boolean + description: "If true, there will be an attempt to lint chart" + isStrictLinted: + type: boolean + description: Strict linting marks the chart as invalid if detect any warning ValidationErrorResponse: type: object properties: @@ -189,3 +189,11 @@ components: type: string templated: type: boolean + examples: + simpleValidation: + description: Example response when parameter isLinted is set to false + value: "{\"renderErrors\":[],\"versionUsed\":\"3.5.2\",\"deployable\":true}" + validationWithLint: + description: Example response when parameter isLinted is set to true + value: "{\"renderErrors\":[],\"lintWarning\":[],\"lintError\":[],\"versionUsed\"\ + :\"3.5.2\",\"valid\":true,\"deployable\":true}" diff --git a/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java b/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java index b766a09..7ce2656 100644 --- a/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java +++ b/src/main/java/org/onap/sdc/helmvalidator/api/ValidationController.java @@ -23,10 +23,13 @@ package org.onap.sdc.helmvalidator.api; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.responses.ApiResponses; import io.swagger.v3.oas.annotations.tags.Tag; +import org.onap.sdc.helmvalidator.config.docs.ValidationRequestParameters; import org.onap.sdc.helmvalidator.errorhandling.ValidationErrorResponse; import org.onap.sdc.helmvalidator.helm.validation.ValidationService; import org.onap.sdc.helmvalidator.helm.validation.model.ValidationResult; @@ -65,7 +68,13 @@ public class ValidationController { */ @ApiResponses(value = { @ApiResponse(responseCode = "200", description = "Helm chart successfully validated", - content = @Content(schema = @Schema(implementation = ValidationResult.class))), + content = { + @Content( + schema = @Schema(implementation = ValidationResult.class), + examples = { + @ExampleObject(ref = "#/components/examples/simpleValidation", name = "Simple Validation"), + @ExampleObject(ref = "#/components/examples/validationWithLint", name = "Lint Validation") + })}), @ApiResponse(responseCode = "400", description = "Chart cannot be validated using selected version", content = @Content(schema = @Schema(implementation = ValidationErrorResponse.class))), @ApiResponse(responseCode = "500", description = "Something went wrong during validation execution", @@ -73,17 +82,25 @@ public class ValidationController { }) @Operation( summary = "Validate chart", - description = "Web endpoint for Helm charts validation.", - tags = "ValidationService") + description = "Web endpoint for Helm charts validation. Helm chart in .tgz format is required.", + tags = "ValidationService", + requestBody = @RequestBody( + required = true, + content = @Content(mediaType = MediaType.MULTIPART_FORM_DATA_VALUE, + schema = @Schema(implementation = ValidationRequestParameters.class) + ) + ) + ) @PostMapping(value = "/validate", produces = "application/json", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public ResponseEntity validate( - @Parameter(description = "Desired Helm version which should be used to validate the chart") + + @Parameter(hidden = true) @RequestParam(value = "versionDesired", required = false) String version, @Parameter(description = "Helm chart that should be validated (packed in .tgz format)", required = true) @RequestParam MultipartFile file, - @Parameter(description = "If false, there will be an attempt to render the chart without linting it first") + @Parameter(hidden = true) @RequestParam(value = "isLinted", required = false, defaultValue = "false") boolean isLinted, - @Parameter(description = "Linting should be strict or not") + @Parameter(hidden = true) @RequestParam(value = "isStrictLinted", required = false, defaultValue = "false") boolean isStrictLinted) { LOGGER.debug("Received file: {}, size: {}, helm version: {}", file.getOriginalFilename(), file.getSize(), version); diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java b/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java deleted file mode 100644 index c2c572f..0000000 --- a/src/main/java/org/onap/sdc/helmvalidator/config/DocsConfiguration.java +++ /dev/null @@ -1,62 +0,0 @@ -/* - * ============LICENSE_START======================================================= - * SDC-HELM-VALIDATOR - * ================================================================================ - * Copyright (C) 2021 Nokia. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * ============LICENSE_END========================================================= - */ - -package org.onap.sdc.helmvalidator.config; - -import io.swagger.v3.oas.annotations.OpenAPIDefinition; -import io.swagger.v3.oas.models.Components; -import io.swagger.v3.oas.models.OpenAPI; -import io.swagger.v3.oas.models.info.Info; -import io.swagger.v3.oas.models.media.ArraySchema; -import io.swagger.v3.oas.models.media.Schema; -import io.swagger.v3.oas.models.media.StringSchema; -import java.util.List; -import java.util.Map; -import org.springframework.context.annotation.Bean; -import org.springframework.context.annotation.Configuration; - -@Configuration -@OpenAPIDefinition -public class DocsConfiguration { - - /** - * Create Open API definition. - * - * @return Custom Open API definition - */ - @Bean - public OpenAPI customOpenApi() { - var versionsSchema = new Schema>>().addProperties("versions", getArraySchema()); - - return new OpenAPI().info( - new Info() - .title("OpenAPI definition for SDC Helm validator") - .version("v0") - .description("Application for validating Helm charts.")) - .components(new Components() - .addSchemas("VersionsResponse", versionsSchema)); - } - - private ArraySchema getArraySchema() { - var arraySchema = new ArraySchema(); - arraySchema.setItems(new StringSchema()); - return arraySchema; - } -} diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java b/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java index 065e642..b8aaef7 100644 --- a/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java +++ b/src/main/java/org/onap/sdc/helmvalidator/config/LoggerConfig.java @@ -50,7 +50,9 @@ public class LoggerConfig { var loggerProperties = new Properties(); loggerProperties.setProperty("logging.level.web", level); loggerProperties.setProperty("logging.level.org.springframework", level); + loggerProperties.setProperty("logging.level.org.springdoc", level); loggerProperties.setProperty("logging.level.org.apache.catalina.core", level); + loggerProperties.setProperty("logging.level.org.apache.tomcat", level); loggerProperties.setProperty("logging.level.org.onap.sdc.helmvalidator", level); loggerProperties.setProperty("spring.mvc.log-request-details", isDebugLevel().toString()); diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java b/src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java new file mode 100644 index 0000000..0e5ceb6 --- /dev/null +++ b/src/main/java/org/onap/sdc/helmvalidator/config/docs/DocsConfiguration.java @@ -0,0 +1,107 @@ +/* + * ============LICENSE_START======================================================= + * SDC-HELM-VALIDATOR + * ================================================================================ + * Copyright (C) 2021 Nokia. All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + +package org.onap.sdc.helmvalidator.config.docs; + +import com.fasterxml.jackson.annotation.JsonInclude.Include; +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.ObjectMapper; +import io.swagger.v3.oas.annotations.OpenAPIDefinition; +import io.swagger.v3.oas.models.Components; +import io.swagger.v3.oas.models.OpenAPI; +import io.swagger.v3.oas.models.examples.Example; +import io.swagger.v3.oas.models.info.Info; +import io.swagger.v3.oas.models.media.ArraySchema; +import io.swagger.v3.oas.models.media.Schema; +import io.swagger.v3.oas.models.media.StringSchema; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import org.onap.sdc.helmvalidator.helm.validation.model.LintValidationResult; +import org.onap.sdc.helmvalidator.helm.validation.model.TemplateValidationResult; +import org.onap.sdc.helmvalidator.helm.validation.model.ValidationResult; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +@Configuration +@OpenAPIDefinition +public class DocsConfiguration { + + private static final String EXAMPLE_VERSION = "3.5.2"; + private static final ValidationResult SIMPLE_VALIDATION_RESPONSE_OBJECT = new ValidationResult( + new TemplateValidationResult(true, Collections.emptyList()), + EXAMPLE_VERSION); + private static final ValidationResult LINT_VALIDATION_RESPONSE_OBJECT = new ValidationResult( + new TemplateValidationResult(true, Collections.emptyList()), + new LintValidationResult(true, Collections.emptyList(), Collections.emptyList()), + EXAMPLE_VERSION); + + /** + * Create Open API definition. + * + * @return Custom Open API definition + */ + @Bean + public OpenAPI customOpenApi() throws JsonProcessingException { + var versionsSchema = new Schema>>().addProperties("versions", getArraySchema()); + + return new OpenAPI().info( + new Info() + .title("OpenAPI definition for SDC Helm validator") + .version("v0") + .description("Application for validating Helm charts.")) + .components(new Components() + .addSchemas("VersionsResponse", versionsSchema) + .addExamples("simpleValidation", getSimpleExample()) + .addExamples("validationWithLint", getLintExample()) + ); + } + + private ArraySchema getArraySchema() { + var arraySchema = new ArraySchema(); + arraySchema.setItems(new StringSchema()); + return arraySchema; + } + + private Example getSimpleExample() throws JsonProcessingException { + var simpleExample = new Example(); + simpleExample.setValue(getJsonResponse(SIMPLE_VALIDATION_RESPONSE_OBJECT)); + simpleExample.setDescription("Example response when parameter isLinted is set to false"); + return simpleExample; + } + + private Example getLintExample() throws JsonProcessingException { + var lintExample = new Example(); + lintExample.setValue(getJsonResponse(LINT_VALIDATION_RESPONSE_OBJECT)); + lintExample.setDescription("Example response when parameter isLinted is set to true"); + return lintExample; + } + + private String getJsonResponse(ValidationResult validationResult) throws JsonProcessingException { + ObjectMapper mapper = getObjectMapper(); + return mapper.writeValueAsString(validationResult); + } + + private ObjectMapper getObjectMapper() { + ObjectMapper mapper = new ObjectMapper(); + mapper.setSerializationInclusion(Include.NON_NULL); + return mapper; + } +} diff --git a/src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java b/src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java new file mode 100644 index 0000000..8c8e038 --- /dev/null +++ b/src/main/java/org/onap/sdc/helmvalidator/config/docs/ValidationRequestParameters.java @@ -0,0 +1,78 @@ +/* + * ============LICENSE_START======================================================= + * SDC-HELM-VALIDATOR + * ================================================================================ + * Copyright (C) 2021 Nokia. All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * ============LICENSE_END========================================================= + */ + + +package org.onap.sdc.helmvalidator.config.docs; + +import io.swagger.v3.oas.annotations.media.Schema; +import org.springframework.web.multipart.MultipartFile; + +@Schema +public class ValidationRequestParameters { + + @Schema(description = "Desired Helm version which should be used to validate the chart. " + + "If parameter is not provided validation is processing with version based on chart's apiVersion." + + " Version could be provided in 'semantic version' or 'major version'.
" + + "Allowed formats:
" + + "- Semantic version [X.Y.Z] e.g. 3.5.2
" + + "- Major version [vX] e.g. v3") + private String versionDesired; + + @Schema(description = "Helm chart that should be validated (packed in .tgz format)", required = true) + private MultipartFile file; + + @Schema(description = "If true, there will be an attempt to lint chart") + private Boolean isLinted; + + @Schema(description = "Strict linting marks the chart as invalid if detect any warning") + private Boolean isStrictLinted; + + public String getVersionDesired() { + return versionDesired; + } + + public void setVersionDesired(String versionDesired) { + this.versionDesired = versionDesired; + } + + public MultipartFile getFile() { + return file; + } + + public void setFile(MultipartFile file) { + this.file = file; + } + + public boolean getIsLinted() { + return isLinted; + } + + public void setIsLinted(boolean linted) { + isLinted = linted; + } + + public boolean getIsStrictLinted() { + return isStrictLinted; + } + + public void setIsStrictLinted(boolean strictLinted) { + isStrictLinted = strictLinted; + } +} diff --git a/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java b/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java index b2ae9e5..19dda3a 100644 --- a/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java +++ b/src/test/java/org/onap/sdc/helmvalidator/config/LoggerConfigTest.java @@ -81,7 +81,9 @@ class LoggerConfigTest { private void assertThatAllLogPropertiesHasExpectedValue(Properties properties, String expectedValue) { assertThat(properties.getProperty("logging.level.web")).isEqualTo(expectedValue); assertThat(properties.getProperty("logging.level.org.springframework")).isEqualTo(expectedValue); + assertThat(properties.getProperty("logging.level.org.springdoc")).isEqualTo(expectedValue); assertThat(properties.getProperty("logging.level.org.apache.catalina.core")).isEqualTo(expectedValue); + assertThat(properties.getProperty("logging.level.org.apache.tomcat")).isEqualTo(expectedValue); assertThat(properties.getProperty("logging.level.org.onap.sdc.helmvalidator")).isEqualTo(expectedValue); } -- cgit 1.2.3-korg