Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Thanks to our sponsors for supporting this project!

### API Info
- API license must be present and non-empty string
- License url and identifier are mutually exclusive, at most one of them may be set (OpenAPI 3.1)
- API description must be present and non-empty string
- API contact must be present and non-empty string

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,29 @@ void shouldNotFailWhenThereAreNoPaths() throws Throwable {

assertDoesNotThrow(() -> validationInitiator.validate(optionManager, commandLine));
}

/**
* See <a href="https://github.com/OpenAPITools/openapi-style-validator/issues/92">https://github.com/OpenAPITools/openapi-style-validator/issues/92</a>
*
* <p>End-to-end, the swagger-parser only carries `license.identifier`
* when the license declares no `url`: a license declaring both is
* reported by the parser itself as an unexpected attribute and the
* identifier never reaches the validator. The flagging of a license
* declaring both is therefore covered by the unit tests of the lib
* module, this only asserts that a 3.1 license using `identifier`
* alone passes the validation.
*/
@Test
void shouldAcceptLicenseWithIdentifierOnly() throws ParseException {
CommandLine commandLine = parser.parse(options, new String[] {
"-s", "src/test/resources/licenseIdentifierOnly.yaml",
"-o", "src/test/resources/default.json"
});

List<StyleError> errorList = validationInitiator.validate(optionManager, commandLine);

assertEquals(0, errorList.size());
}
}

private void assertThrowsIllegalArgumentExceptionWithExceptedMessage(
Expand Down
24 changes: 24 additions & 0 deletions cli/src/test/resources/licenseIdentifierOnly.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
openapi: 3.1.0
info:
title: Example specification
version: '1.0'
description: Example API
contact:
name: OpenAPI Tools
email: team@openapitools.org
license:
name: Eclipse Public License 2.0
identifier: EPL-2.0
servers:
- url: 'http://localhost:8080/'
paths:
/ping:
get:
operationId: ping
summary: A simple get call
description: When this method is called, the server answers with 200 OKs
tags:
- demo
responses:
'200':
description: OK
1 change: 1 addition & 0 deletions lib/build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ dependencies {
implementation 'org.eclipse.microprofile.openapi:microprofile-openapi-api:3.1.1'
testImplementation 'org.slf4j:slf4j-jdk14:2.0.16'
testImplementation 'org.openapitools.empoa:empoa-simple-models-impl:2.1.0'
testImplementation 'io.swagger.core.v3:swagger-models:2.2.23'
testImplementation 'nl.jqno.equalsverifier:equalsverifier:3.16.2'
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,14 @@ void validateMinimumInfo(
}
}

void logLicenseUrlAndIdentifierBothSet() {
errorList.add(new GenericStyleError(
StyleError.StyleCheckSection.APIInfo,
"license",
"url|identifier",
"The license url and identifier are mutually exclusive, only one of them should be set"));
}

List<StyleError> getErrorList() {
return errorList;
}
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package org.openapitools.openapistylevalidator;

import java.lang.reflect.Method;
import java.util.*;
import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.eclipse.microprofile.openapi.models.Operation;
Expand Down Expand Up @@ -46,6 +47,42 @@ private void validateStructure() {
}
}

/*
* The `identifier` field of the license object was introduced by OpenAPI
* 3.1.0. The MicroProfile OpenAPI API this library is built against (3.1)
* predates it and declares no `identifier` accessor: `getIdentifier()`
* exists only on models aligned with OAS 3.1, such as the MicroProfile
* OpenAPI 4.0 API.
*
* The CLI, Gradle and Maven plugins parse specifications with
* swagger-parser and convert the result through empoa-swagger-core, whose
* wrapper keeps the underlying swagger model - which does carry
* `identifier` - behind its `getSw()` accessor.
*
* Both situations are handled reflectively so the check works with any of
* them; when neither is available, no identifier is reported.
* See https://github.com/OpenAPITools/openapi-style-validator/issues/92
*/
private static String getLicenseIdentifier(License license) {
try {
Method getIdentifier = license.getClass().getMethod("getIdentifier");
return (String) getIdentifier.invoke(license);
} catch (NoSuchMethodException e) {
// The model has no identifier accessor: try the swagger model behind an empoa wrapper, if any
} catch (ReflectiveOperationException e) {
return null;
}

try {
Method getSw = license.getClass().getMethod("getSw");
Object swaggerLicense = getSw.invoke(license);
Method getIdentifier = swaggerLicense.getClass().getMethod("getIdentifier");
return (String) getIdentifier.invoke(swaggerLicense);
} catch (ReflectiveOperationException e) {
return null;
}
}

private void validateInfo() {
Info info = openAPI.getInfo();
License license = info.getLicense();
Expand All @@ -56,6 +93,20 @@ private void validateInfo() {
infoPresence.add(license.getUrl() != null && !license.getUrl().isEmpty());
errorAggregator.validateMinimumInfo(
infoPresence, StyleError.StyleCheckSection.APIInfo, "license", "name|url");

/*
* See https://github.com/OpenAPITools/openapi-style-validator/issues/92
*
* In an OpenAPI 3.1.0 document the `identifier` field of the
* license object is mutually exclusive of the `url` field.
*/
String identifier = getLicenseIdentifier(license);
if (license.getUrl() != null
&& !license.getUrl().isEmpty()
&& identifier != null
&& !identifier.isEmpty()) {
Comment thread
Inf1mum marked this conversation as resolved.
Resolved
errorAggregator.logLicenseUrlAndIdentifierBothSet();
}
} else {
errorAggregator.logMissingOrEmptyAttribute(StyleError.StyleCheckSection.APIInfo, "license");
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,4 +45,15 @@ void logMissingModelProperty() {
nameOfMissingProperty);
assertEquals(Collections.singletonList(expectedError), errorAggregator.getErrorList());
}

@Test
void logLicenseUrlAndIdentifierBothSetShouldAddToErrorList() {
errorAggregator.logLicenseUrlAndIdentifierBothSet();

Assertions.assertAll(
() -> assertEquals(1, errorAggregator.getErrorList().size()),
() -> assertEquals(
"*ERROR* Section: APIInfo: 'url|identifier' in license -> The license url and identifier are mutually exclusive, only one of them should be set",
errorAggregator.getErrorList().get(0).toString()));
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,15 @@
import java.util.stream.Collectors;
import org.eclipse.microprofile.openapi.OASFactory;
import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.eclipse.microprofile.openapi.models.info.License;
import org.eclipse.microprofile.openapi.models.media.Schema;
import org.eclipse.microprofile.openapi.models.media.Schema.SchemaType;
import org.eclipse.microprofile.openapi.models.parameters.Parameter.In;
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.openapitools.empoa.simple.internal.models.info.LicenseImpl;
import org.openapitools.openapistylevalidator.ValidatorParameters.NamingConvention;
import org.openapitools.openapistylevalidator.styleerror.StyleError;

Expand Down Expand Up @@ -221,6 +223,125 @@ void testSuccessOfAllValidations() {
assertEquals(0, errors.size(), errors.toString());
}

/*
* See https://github.com/OpenAPITools/openapi-style-validator/issues/92
*
* Plain @Test methods are used on purpose: junit-jupiter-params is
* declared testCompileOnly in the root build.gradle, so @ParameterizedTest
* methods compile but are silently skipped at runtime.
*/
@Test
void testLicenseUrlOnlyIsValid() {
OpenAPI openAPI = createValidOpenAPI();
openAPI.getInfo()
.license(OASFactory.createLicense()
.name("Eclipse Public License 2.0")
.url("https://www.eclipse.org/legal/epl-2.0/"));

ValidatorParameters parameters =
TestDataProvider.createParametersDisablingAllValidations().setValidateInfoLicense(true);

List<StyleError> errors = new OpenApiSpecStyleValidator(openAPI).validate(parameters);
assertEquals(0, errors.size());
}

/*
* The simple model has no identifier accessor, so this fake provides one
* the way an OAS 3.1-aware model (e.g. MicroProfile OpenAPI 4.0) does.
*/
private static License licenseWithIdentifier(String url, String identifier) {
return new LicenseImpl() {
@SuppressWarnings("unused")
public String getIdentifier() {
return identifier;
}
}.name("Eclipse Public License 2.0").url(url);
}

/*
* Mimics the license wrapper produced by empoa-swagger-core (SwLicense),
* which delegates name and url but keeps the underlying swagger model -
* carrying `identifier` - accessible only through its `getSw()` accessor.
*/
private static License licenseThroughSwaggerModel(String url, String identifier) {
io.swagger.v3.oas.models.info.License swaggerLicense = new io.swagger.v3.oas.models.info.License()
.name("Eclipse Public License 2.0")
.url(url)
.identifier(identifier);
return new LicenseImpl() {
@SuppressWarnings("unused")
public io.swagger.v3.oas.models.info.License getSw() {
return swaggerLicense;
}
}.name("Eclipse Public License 2.0").url(url);
}

@Test
void testLicenseIdentifierOnlyIsValid() {
OpenAPI openAPI = createValidOpenAPI();
openAPI.getInfo().license(licenseWithIdentifier(null, "EPL-2.0"));

ValidatorParameters parameters =
TestDataProvider.createParametersDisablingAllValidations().setValidateInfoLicense(true);

List<StyleError> errors = new OpenApiSpecStyleValidator(openAPI).validate(parameters);
assertEquals(0, errors.size());
}

@Test
void testLicenseUrlAndIdentifierAreMutuallyExclusive() {
OpenAPI openAPI = createValidOpenAPI();
openAPI.getInfo().license(licenseWithIdentifier("https://www.eclipse.org/legal/epl-2.0/", "EPL-2.0"));

ValidatorParameters parameters =
TestDataProvider.createParametersDisablingAllValidations().setValidateInfoLicense(true);

List<StyleError> errors = new OpenApiSpecStyleValidator(openAPI).validate(parameters);
Assertions.assertAll(
() -> assertEquals(1, errors.size()),
() -> assertEquals(
"*ERROR* Section: APIInfo: 'url|identifier' in license -> The license url and identifier are mutually exclusive, only one of them should be set",
errors.get(0).toString()));
}

/*
* The CLI, Gradle and Maven plugins convert the parsed specification to
* MicroProfile models through empoa-swagger-core: the license is a wrapper
* around the swagger model, which carries `identifier` even though the
* wrapper does not expose it.
*/
@Test
void testLicenseUrlAndIdentifierAreMutuallyExclusiveThroughSwaggerModel() {
OpenAPI openAPI = createValidOpenAPI();
openAPI.getInfo().license(licenseThroughSwaggerModel("https://www.eclipse.org/legal/epl-2.0/", "EPL-2.0"));

ValidatorParameters parameters =
TestDataProvider.createParametersDisablingAllValidations().setValidateInfoLicense(true);

List<StyleError> errors = new OpenApiSpecStyleValidator(openAPI).validate(parameters);
Assertions.assertAll(
() -> assertEquals(1, errors.size()),
() -> assertEquals(
"*ERROR* Section: APIInfo: 'url|identifier' in license -> The license url and identifier are mutually exclusive, only one of them should be set",
errors.get(0).toString()));
}

/*
* A license carrying only an identifier behind the swagger model is valid:
* the two fields must not be flagged when they are not both set.
*/
@Test
void testLicenseIdentifierOnlyIsValidThroughSwaggerModel() {
OpenAPI openAPI = createValidOpenAPI();
openAPI.getInfo().license(licenseThroughSwaggerModel(null, "EPL-2.0"));

ValidatorParameters parameters =
TestDataProvider.createParametersDisablingAllValidations().setValidateInfoLicense(true);

List<StyleError> errors = new OpenApiSpecStyleValidator(openAPI).validate(parameters);
assertEquals(0, errors.size());
}

/**
* See https://github.com/OpenAPITools/openapi-style-validator/issues/190
*/
Expand Down