[7.x] Validate REST specs against schema (#55117) (#55563)

A JSON schema was recently introduced for the REST API specification. #54252
This PR introduces a 3rd party validation tool to ensure that the
REST specification conforms to the schema.

The task is applied to the 3 projects that contain REST API specifications.
The plugin wires this task into the precommit commit task, and should be
considered as part of the public API for the build tools for any plugin
developer to contribute their plugin's specification.

An ignore parameter has been introduced for the task to allow specific
file to be ignored from the validation. The ignored files in this PR
will soon get issues logged and a link so they can be fixed.

Closes #54314
This commit is contained in:
Jake Landis 2020-04-22 14:14:03 -05:00 committed by GitHub
parent 82ed0ab420
commit 25ea6a74f0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 292 additions and 1 deletions

View File

@ -119,6 +119,7 @@ dependencies {
compile 'de.thetaphi:forbiddenapis:2.7'
compile 'com.avast.gradle:gradle-docker-compose-plugin:0.8.12'
compile 'org.apache.maven:maven-model:3.6.2'
compile 'com.networknt:json-schema-validator:1.0.36'
compileOnly "com.puppycrawl.tools:checkstyle:${props.getProperty('checkstyle')}"
testCompile "com.puppycrawl.tools:checkstyle:${props.getProperty('checkstyle')}"
testCompile "junit:junit:${props.getProperty('junit')}"

View File

@ -0,0 +1,152 @@
/*
* Licensed to Elasticsearch under one or more contributor
* license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright
* ownership. Elasticsearch licenses this file to you 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.
*/
package org.elasticsearch.gradle.precommit;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.networknt.schema.JsonSchema;
import com.networknt.schema.JsonSchemaException;
import com.networknt.schema.JsonSchemaFactory;
import com.networknt.schema.SchemaValidatorsConfig;
import com.networknt.schema.SpecVersion;
import com.networknt.schema.ValidationMessage;
import org.gradle.api.DefaultTask;
import org.gradle.api.UncheckedIOException;
import org.gradle.api.file.FileCollection;
import org.gradle.api.tasks.Input;
import org.gradle.api.tasks.InputFile;
import org.gradle.api.tasks.InputFiles;
import org.gradle.api.tasks.Optional;
import org.gradle.api.tasks.OutputFile;
import org.gradle.api.tasks.TaskAction;
import org.gradle.work.ChangeType;
import org.gradle.work.Incremental;
import org.gradle.work.InputChanges;
import java.io.File;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Arrays;
import java.util.Collection;
import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.LinkedHashSet;
import java.util.Map;
import java.util.Set;
import java.util.stream.StreamSupport;
/**
* Incremental task to validate a set of JSON files against against a schema.
*/
public class ValidateJsonAgainstSchemaTask extends DefaultTask {
private final ObjectMapper mapper = new ObjectMapper();
private Set<String> ignore = new HashSet<>();
private File jsonSchema;
private FileCollection inputFiles;
@Incremental
@InputFiles
public FileCollection getInputFiles() {
return inputFiles;
}
public void setInputFiles(FileCollection inputFiles) {
this.inputFiles = inputFiles;
}
@InputFile
public File getJsonSchema() {
return jsonSchema;
}
public void setJsonSchema(File jsonSchema) {
this.jsonSchema = jsonSchema;
}
@Input
@Optional
public Set<String> getIgnore() {
return ignore;
}
public void ignore(String... ignore) {
this.ignore.addAll(Arrays.asList(ignore));
}
@OutputFile
public File getReport() {
return new File(getProject().getBuildDir(), "reports/validateJson.txt");
}
@TaskAction
public void validate(InputChanges inputChanges) throws IOException {
File jsonSchemaOnDisk = getJsonSchema();
getLogger().debug("JSON schema : [{}]", jsonSchemaOnDisk.getAbsolutePath());
SchemaValidatorsConfig config = new SchemaValidatorsConfig();
JsonSchemaFactory factory = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V7);
JsonSchema jsonSchema = factory.getSchema(mapper.readTree(jsonSchemaOnDisk), config);
Map<File, Set<String>> errors = new LinkedHashMap<>();
// incrementally evaluate input files
StreamSupport.stream(inputChanges.getFileChanges(getInputFiles()).spliterator(), false)
.filter(f -> f.getChangeType() != ChangeType.REMOVED)
.forEach(fileChange -> {
File file = fileChange.getFile();
if (ignore.contains(file.getName())) {
getLogger().debug("Ignoring file [{}] due to configuration", file.getName());
} else if (file.isDirectory() == false) {
// validate all files and hold on to errors for a complete report if there are failures
getLogger().debug("Validating JSON [{}]", file.getName());
try {
Set<ValidationMessage> validationMessages = jsonSchema.validate(mapper.readTree(file));
maybeLogAndCollectError(validationMessages, errors, file);
} catch (IOException e) {
throw new UncheckedIOException(e);
}
}
});
if (errors.isEmpty()) {
try (PrintWriter printWriter = new PrintWriter(getReport())) {
printWriter.println("Success! No validation errors found.");
}
} else {
try (PrintWriter printWriter = new PrintWriter(getReport())) {
printWriter.printf("Schema: %s%n", jsonSchemaOnDisk);
printWriter.println("----------Validation Errors-----------");
errors.values().stream().flatMap(Collection::stream).forEach(printWriter::println);
}
StringBuilder sb = new StringBuilder();
sb.append("Error validating JSON. See the report at: ");
sb.append(getReport().toURI().toASCIIString());
sb.append(System.lineSeparator());
sb.append(
String.format("JSON validation failed: %d files contained %d violations", errors.keySet().size(), errors.values().size())
);
throw new JsonSchemaException(sb.toString());
}
}
private void maybeLogAndCollectError(Set<ValidationMessage> messages, Map<File, Set<String>> errors, File file) {
for (ValidationMessage message : messages) {
getLogger().error("[validate JSON][ERROR][{}][{}]", file.getName(), message.toString());
errors.computeIfAbsent(file, k -> new LinkedHashSet<>())
.add(String.format("%s: %s", file.getAbsolutePath(), message.toString()));
}
}
}

View File

@ -0,0 +1,44 @@
/*
* Licensed to Elasticsearch under one or more contributor
* license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright
* ownership. Elasticsearch licenses this file to you 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.
*/
package org.elasticsearch.gradle.precommit;
import org.elasticsearch.gradle.util.Util;
import org.gradle.api.Plugin;
import org.gradle.api.Project;
import org.gradle.api.provider.Provider;
import java.io.File;
public class ValidateRestSpecPlugin implements Plugin<Project> {
private static final String DOUBLE_STAR = "**"; // checkstyle thinks these are javadocs :(
@Override
public void apply(Project project) {
Provider<ValidateJsonAgainstSchemaTask> validateRestSpecTask = project.getTasks()
.register("validateRestSpec", ValidateJsonAgainstSchemaTask.class, task -> {
task.setInputFiles(Util.getJavaTestAndMainSourceResources(project, filter -> {
filter.include(DOUBLE_STAR + "/rest-api-spec/api/" + DOUBLE_STAR + "/*.json");
filter.exclude(DOUBLE_STAR + "/_common.json");
}));
task.setJsonSchema(new File(project.getRootDir(), "rest-api-spec/src/main/resources/schema.json"));
});
project.getTasks().named("precommit").configure(t -> t.dependsOn(validateRestSpecTask));
}
}

View File

@ -20,8 +20,15 @@
package org.elasticsearch.gradle.util;
import org.elasticsearch.gradle.info.GlobalBuildInfoPlugin;
import org.gradle.api.Action;
import org.gradle.api.GradleException;
import org.gradle.api.Project;
import org.gradle.api.file.FileTree;
import org.gradle.api.plugins.JavaPluginConvention;
import org.gradle.api.tasks.SourceSet;
import org.gradle.api.tasks.util.PatternFilterable;
import javax.annotation.Nullable;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
@ -29,6 +36,7 @@ import java.io.UncheckedIOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.Locale;
import java.util.Optional;
public class Util {
@ -75,4 +83,65 @@ public class Util {
throw new GradleException("Error determining build tools JAR location", e);
}
}
/**
* @param project The project to look for resources.
* @param filter Optional filter function to filter the returned resources
* @return Returns the {@link FileTree} for main resources from Java projects. Returns null if no files exist.
*/
@Nullable
public static FileTree getJavaMainSourceResources(Project project, Action<? super PatternFilterable> filter) {
final Optional<FileTree> mainFileTree = getJavaMainSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
return mainFileTree.map(files -> files.matching(filter)).orElse(null);
}
/**
* @param project The project to look for resources.
* @param filter Optional filter function to filter the returned resources
* @return Returns the {@link FileTree} for test resources from Java projects. Returns null if no files exist.
*/
@Nullable
public static FileTree getJavaTestSourceResources(Project project, Action<? super PatternFilterable> filter) {
final Optional<FileTree> testFileTree = getJavaTestSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
return testFileTree.map(files -> files.matching(filter)).orElse(null);
}
/**
* @param project The project to look for resources.
* @param filter Optional filter function to filter the returned resources
* @return Returns the combined {@link FileTree} for test and main resources from Java projects. Returns null if no files exist.
*/
@Nullable
public static FileTree getJavaTestAndMainSourceResources(Project project, Action<? super PatternFilterable> filter) {
final Optional<FileTree> testFileTree = getJavaTestSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
final Optional<FileTree> mainFileTree = getJavaMainSourceSet(project).map(SourceSet::getResources).map(FileTree::getAsFileTree);
if (testFileTree.isPresent() && mainFileTree.isPresent()) {
return testFileTree.get().plus(mainFileTree.get()).matching(filter);
} else if (mainFileTree.isPresent()) {
return mainFileTree.get().matching(filter);
} else if (testFileTree.isPresent()) {
return testFileTree.get().matching(filter);
}
return null;
}
/**
* @param project The project to look for test Java resources.
* @return An Optional that contains the Java test SourceSet if it exists.
*/
public static Optional<SourceSet> getJavaTestSourceSet(Project project) {
return project.getConvention().findPlugin(JavaPluginConvention.class) == null
? Optional.empty()
: Optional.ofNullable(GradleUtils.getJavaSourceSets(project).findByName(SourceSet.TEST_SOURCE_SET_NAME));
}
/**
* @param project The project to look for main Java resources.
* @return An Optional that contains the Java main SourceSet if it exists.
*/
public static Optional<SourceSet> getJavaMainSourceSet(Project project) {
return project.getConvention().findPlugin(JavaPluginConvention.class) == null
? Optional.empty()
: Optional.ofNullable(GradleUtils.getJavaSourceSets(project).findByName(SourceSet.MAIN_SOURCE_SET_NAME));
}
}

View File

@ -0,0 +1 @@
implementation-class=org.elasticsearch.gradle.precommit.ValidateRestSpecPlugin

View File

@ -16,7 +16,9 @@
* specific language governing permissions and limitations
* under the License.
*/
import org.elasticsearch.gradle.testclusters.DefaultTestClustersTask;
apply plugin: 'elasticsearch.validate-rest-spec'
esplugin {
description 'An easy, safe and fast scripting language for Elasticsearch'
@ -191,3 +193,7 @@ task regen {
}
}
}
validateRestSpec {
ignore 'scripts_painless_context.json'
}

View File

@ -1,6 +1,7 @@
apply plugin: 'elasticsearch.build'
apply plugin: 'nebula.maven-base-publish'
apply plugin: 'elasticsearch.rest-resources'
apply plugin: 'elasticsearch.validate-rest-spec'
test.enabled = false
jarHell.enabled = false
@ -9,3 +10,8 @@ artifacts {
restSpecs(new File(projectDir, "src/main/resources/rest-api-spec/api"))
restTests(new File(projectDir, "src/main/resources/rest-api-spec/test"))
}
validateRestSpec {
ignore "cat.thread_pool.json"
ignore "indices.put_mapping.json"
}

View File

@ -142,7 +142,7 @@
"description"
],
"title": "Documentation",
"description": "API documentation including a link to the public reference and a short descritpion"
"description": "API documentation including a link to the public reference and a short description"
},
"Parts": {
"type": "object",

View File

@ -7,6 +7,7 @@ import java.nio.charset.StandardCharsets
apply plugin: 'elasticsearch.testclusters'
apply plugin: 'elasticsearch.standalone-rest-test'
apply plugin: 'elasticsearch.rest-test'
apply plugin: 'elasticsearch.validate-rest-spec'
archivesBaseName = 'x-pack'
@ -155,3 +156,14 @@ testClusters.integTest {
extraConfigFile 'roles.yml', file('src/test/resources/roles.yml')
}
validateRestSpec {
ignore 'searchable_snapshots.mount.json'
ignore 'searchable_snapshots.clear_cache.json'
ignore 'searchable_snapshots.stats.json'
ignore 'searchable_snapshots.repository_stats.json'
ignore 'autoscaling.delete_autoscaling_policy.json'
ignore 'autoscaling.get_autoscaling_policy.json'
ignore 'autoscaling.put_autoscaling_policy.json'
ignore 'ml.validate.json'
ignore 'ml.validate_detector.json'
}