Add MP OpenAPI support to Helidon MP

microprofile/openapi/etc/spotbugs/exclude.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Copyright (c) 2019 Oracle and/or its affiliates. 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.
+
+-->
+
+<FindBugsFilter
+              xmlns="https://github.com/spotbugs/filter/3.0.0"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd">
+
+    <!-- We need the following because of SpotBugs issue 493 
+         https://github.com/spotbugs/spotbugs/issues/493 (false positives with
+         try-with-resource blocks).
+    -->
+    <Match>
+        <Class name="io.helidon.microprofile.openapi.IndexBuilder"/>
+        <Method name="checkForIndexFile" />
+        <Bug pattern="OBL_UNSATISFIED_OBLIGATION" />
+    </Match>
+</FindBugsFilter>

microprofile/openapi/pom.xml

@@ -0,0 +1,107 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright (c) 2019 Oracle and/or its affiliates. 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.
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0" 
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>io.helidon.microprofile</groupId>
+        <artifactId>helidon-microprofile-project</artifactId>
+        <version>1.1.1-SNAPSHOT</version>
+    </parent>
+    <groupId>io.helidon.microprofile.openapi</groupId>
+    <artifactId>helidon-microprofile-openapi</artifactId>
+
+    <name>Helidon Microprofile OpenAPI</name>
+
+    <description>
+        Helidon Microprofile OpenAPI implementation
+    </description>
+
+    <packaging>jar</packaging>
+
+    <properties>
+        <spotbugs.exclude>etc/spotbugs/exclude.xml</spotbugs.exclude>
+    </properties>
+
+    <build>
+        <plugins>
+            <plugin>
+                <!--
+                    Used for the BasicServerTest.
+                -->
+                <groupId>org.jboss.jandex</groupId>
+                <artifactId>jandex-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>make-test-index</id>
+                        <goals>
+                            <goal>jandex</goal>
+                        </goals>
+                        <phase>process-test-classes</phase>
+                        <configuration>
+                            <classesDir>${project.build.directory}/test-classes</classesDir>
+                            <fileSets>
+                                <fileSet>
+                                    <directory>${project.build.directory}/test-classes</directory>
+                                </fileSet>
+                            </fileSets>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.eclipse.microprofile.config</groupId>
+            <artifactId>microprofile-config-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.microprofile.server</groupId>
+            <artifactId>helidon-microprofile-server</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>io.helidon.openapi</groupId>
+            <artifactId>helidon-openapi</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.yaml</groupId>
+            <artifactId>snakeyaml</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+</project>

microprofile/openapi/src/main/java/io/helidon/microprofile/openapi/IndexBuilder.java

@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 2019 Oracle and/or its affiliates. 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.
+ *
+ */
+package io.helidon.microprofile.openapi;
+
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.PrintStream;
+import java.io.UnsupportedEncodingException;
+import java.nio.charset.Charset;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import javax.enterprise.event.Observes;
+import javax.enterprise.inject.spi.Extension;
+import javax.enterprise.inject.spi.ProcessAnnotatedType;
+
+import org.jboss.jandex.Index;
+import org.jboss.jandex.IndexReader;
+import org.jboss.jandex.IndexView;
+import org.jboss.jandex.Indexer;
+
+/**
+ * Portable extension to allow construction of a Jandex index (to pass to
+ * SmallRye OpenAPI) from CDI if no {@code META-INF/jandex.idx} file exists on
+ * the class path.
+ */
+public class IndexBuilder implements Extension {
+
+    private static final String INDEX_PATH = "/META-INF/jandex.idx";
+
+    private static final Logger LOGGER = Logger.getLogger(IndexBuilder.class.getName());
+
+    private final boolean isIndexPresentOnClasspath;
+
+    private final Set<Class<?>> annotatedTypes = new HashSet<>();
+
+    /**
+     * Creates a new instance of the index builder.
+     *
+     * @throws IOException in case of error checking for the Jandex index file
+     */
+    public IndexBuilder() throws IOException {
+        isIndexPresentOnClasspath = checkForIndexFile();
+        if (isIndexPresentOnClasspath) {
+            LOGGER.log(Level.FINE, () -> String.format("Index file %s was located and will be used", INDEX_PATH));
+        } else {
+            LOGGER.log(Level.INFO, () -> String.format(
+                    "OpenAPI support could not locate the index file %s "
+                    + "so will build an in-memory index. This slows your app start-up.%n"
+                    + "Consider using the jandex maven plug-in to build the index "
+                    + "and add it to your app at build-time",
+                    INDEX_PATH));
+        }
+    }
+
+    /**
+     * Records each type that is annotated unless a Jandex index was found on
+     * the classpath (in which case we do not need to build our own in memory).
+     *
+     * @param <X> annotated type
+     * @param event {@code ProcessAnnotatedType} event
+     */
+    private <X> void processAnnotatedType(@Observes ProcessAnnotatedType<X> type) {
+        if (isIndexPresentOnClasspath) {
+            return;
+        }
+        Class<?> c = type.getAnnotatedType().getJavaClass();
+        annotatedTypes.add(c);
+    }
+
+    /**
+     * Reports an {@link IndexView} for the Jandex index that describes
+     * annotated classes for endpoints.
+     *
+     * @return {@code IndexView} describing discovered classes
+     * @throws IOException in case of error reading an existing index file or
+     * reading class bytecode from the classpath
+     */
+    public IndexView indexView() throws IOException {
+        return isIndexPresentOnClasspath ? existingIndexFileReader() : indexFromHarvestedClasses();
+    }
+
+    private IndexView existingIndexFileReader() throws IOException {
+        try (InputStream jandexIS = getClass().getResourceAsStream(INDEX_PATH)) {
+            if (jandexIS == null) {
+                throw new IllegalArgumentException("Attempted to read from previously-located index file "
+                        + INDEX_PATH + " but the file cannot be found");
+            }
+            LOGGER.log(Level.FINE, "Using Jandex index at {0}", INDEX_PATH);
+            return new IndexReader(jandexIS).read();
+        }
+    }
+
+    private IndexView indexFromHarvestedClasses() throws IOException {
+        Indexer indexer = new Indexer();
+        for (Class<?> c : annotatedTypes) {
+            try (InputStream is = contextClassLoader().getResourceAsStream(resourceNameForClass(c))) {
+                if (is == null) {
+                    throw new IllegalArgumentException("Cannot load bytecode from class "
+                            + c.getName() + " at " + resourceNameForClass(c)
+                            + " for annotation processing");
+                }
+                indexer.index(is);
+            }
+        }
+
+        LOGGER.log(Level.FINE, "Using internal Jandex index created from CDI bean discovery");
+        Index result = indexer.complete();
+        dumpIndex(Level.FINER, result);
+        return result;
+    }
+
+    private boolean checkForIndexFile() throws IOException {
+        try (InputStream jandexIS = getClass().getResourceAsStream(INDEX_PATH)) {
+            return jandexIS != null;
+        }
+    }
+
+    private static void dumpIndex(Level level, Index index) throws UnsupportedEncodingException {
+        if (LOGGER.isLoggable(level)) {
+            LOGGER.log(level, "Dump of internal Jandex index:");
+            PrintStream oldStdout = System.out;
+            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+            try (PrintStream newPS = new PrintStream(baos, true, Charset.defaultCharset().name())) {
+                System.setOut(newPS);
+                index.printAnnotations();
+                index.printSubclasses();
+                LOGGER.log(level, baos.toString(Charset.defaultCharset().name()));
+            } finally {
+                System.setOut(oldStdout);
+            }
+        }
+    }
+
+    private static ClassLoader contextClassLoader() {
+        return Thread.currentThread().getContextClassLoader();
+    }
+
+    private static String resourceNameForClass(Class<?> c) {
+        return c.getName().replace('.', '/') + ".class";
+    }
+}

microprofile/openapi/src/main/java/io/helidon/microprofile/openapi/MPOpenAPIBuilder.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2019 Oracle and/or its affiliates. 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.
+ *
+ */
+package io.helidon.microprofile.openapi;
+
+import java.util.Optional;
+
+import io.helidon.openapi.OpenAPISupport;
+
+import io.smallrye.openapi.api.OpenApiConfig;
+import org.jboss.jandex.IndexView;
+
+/**
+ * Fluent builder for OpenAPISupport in Helidon MP.
+ */
+public final class MPOpenAPIBuilder extends OpenAPISupport.Builder {
+
+    private Optional<OpenApiConfig> openAPIConfig;
+    private Optional<IndexView> indexView;
+
+    @Override
+    public OpenApiConfig openAPIConfig() {
+        return openAPIConfig.get();
+    }
+
+    @Override
+    public IndexView indexView() {
+        return indexView.get();
+    }
+
+    /**
+     * Sets the OpenApiConfig instance to use in governing the behavior of the
+     * smallrye OpenApi implementation.
+     *
+     * @param config {@link OpenApiConfig} instance to control OpenAPI behavior
+     * @return updated builder instance
+     */
+    public MPOpenAPIBuilder openAPIConfig(OpenApiConfig config) {
+        this.openAPIConfig = Optional.of(config);
+        return this;
+    }
+
+    /**
+     * Sets the IndexView instance to be passed to the smallrye OpenApi impl for
+     * annotation analysis.
+     *
+     * @param indexView {@link IndexView} instance containing endpoint classes
+     * @return updated builder instance
+     */
+    public MPOpenAPIBuilder indexView(IndexView indexView) {
+        this.indexView = Optional.of(indexView);
+        return this;
+    }
+
+    @Override
+    public void validate() throws IllegalStateException {
+        if (!openAPIConfig.isPresent()) {
+            throw new IllegalStateException("OpenApiConfig has not been set in MPBuilder");
+        }
+    }
+
+}