Adding OpenAPI in the Reactive Routes Guide

bom/application/pom.xml

@@ -36,7 +36,7 @@
         <smallrye-config.version>1.8.4</smallrye-config.version>
         <smallrye-health.version>2.2.3</smallrye-health.version>
         <smallrye-metrics.version>2.4.2</smallrye-metrics.version>
-        <smallrye-open-api.version>2.0.4</smallrye-open-api.version>
+        <smallrye-open-api.version>2.0.5</smallrye-open-api.version>
         <smallrye-graphql.version>1.0.5</smallrye-graphql.version>
         <smallrye-opentracing.version>1.3.4</smallrye-opentracing.version>
         <smallrye-fault-tolerance.version>4.3.0</smallrye-fault-tolerance.version>

docs/src/main/asciidoc/reactive-routes.adoc

@@ -352,7 +352,7 @@ Multi<Person> people(RoutingContext context) {
 }
 ----
 
-Ths previous snippet produces:
+The previous snippet produces:
 
 [source, json]
 ----
@@ -380,7 +380,7 @@ Multi<Person> people(RoutingContext context) {
 }
 ----
 
-Ths previous snippet produces:
+The previous snippet produces:
 
 [source, json]
 ----
@@ -522,6 +522,171 @@ public class MyFilters {
 <1> The `RouteFilter#value()` defines the priority used to sort the filters - filters with higher priority are called first.
 <2> The filter is likely required to call the `next()` method to continue the chain.
 
+== Adding OpenAPI and Swagger UI
+
+You can add support for link:https://www.openapis.org/[OpenAPI] and link:https://swagger.io/tools/swagger-ui/[Swagger UI] by using the `quarkus-smallrye-openapi` extension.
+
+Add the extension by running this command:
+
+[source,bash]
+----
+./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-smallrye-openapi"
+----
+
+This will add the following to your `pom.xml`:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-smallrye-openapi</artifactId>
+</dependency>
+----
+
+This is enough to generate a basic OpenAPI schema document from your Vert.x Routes:
+
+[source,bash]
+----
+curl http://localhost:8080/openapi
+----
+
+You will see the generated OpenAPI schema document:
+
+[source, yaml]
+----
+---
+openapi: 3.0.3
+info:
+  title: Generated API
+  version: "1.0"
+paths:
+  /greetings:
+    get:
+      responses:
+        "204":
+          description: No Content
+  /hello:
+    get:
+      responses:
+        "204":
+          description: No Content
+  /world:
+    get:
+      responses:
+        "200":
+          description: OK
+          content:
+            '*/*':
+              schema:
+                type: string
+----
+
+Also see <<openapi-swaggerui.adoc,the OpenAPI Guide>>
+
+=== Adding MicroProfile OpenAPI Annotations
+
+You can use link:https://github.com/eclipse/microprofile-open-api[MicroProfile OpenAPI] to better document your schema, 
+example, adding header info, or specifying the return type on `void` methods might be usefull :
+
+[source, java]
+----
+@OpenAPIDefinition(<1>
+    info = @Info(
+        title="Greeting API",
+        version = "1.0.1",
+        contact = @Contact(
+            name = "Greeting API Support",
+            url = "http://exampleurl.com/contact",
+            email = "[email protected]"),
+        license = @License(
+            name = "Apache 2.0",
+            url = "http://www.apache.org/licenses/LICENSE-2.0.html"))
+)
+@ApplicationScoped
+public class MyDeclarativeRoutes {
+
+    // neither path nor regex is set - match a path derived from the method name
+    @Route(methods = HttpMethod.GET)
+    @APIResponse(responseCode="200", 
+            description="Say hello", 
+            content=@Content(mediaType="application/json", schema=@Schema(type=SchemaType.STRING)))<2>
+    void hello(RoutingContext rc) {
+        rc.response().end("hello");
+    }
+
+    @Route(path = "/world") 
+    String helloWorld() {
+        return "Hello world!";
+    }
+
+    @Route(path = "/greetings", methods = HttpMethod.GET)
+    @APIResponse(responseCode="200", 
+            description="Greeting", 
+            content=@Content(mediaType="application/json", schema=@Schema(type=SchemaType.STRING)))
+    void greetings(RoutingExchange ex) {
+        ex.ok("hello " + ex.getParam("name").orElse("world"));
+    }
+}
+----
+
+<1> Header information about your API.
+<2> Defining the response
+
+This will generate this OpenAPI schema:
+
+[source, yaml]
+----
+---
+openapi: 3.0.3
+info:
+  title: Greeting API
+  contact:
+    name: Greeting API Support
+    url: http://exampleurl.com/contact
+    email: [email protected]
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0.html
+  version: 1.0.1
+paths:
+  /greetings:
+    get:
+      responses:
+        "200":
+          description: Greeting
+          content:
+            application/json:
+              schema:
+                type: string
+  /hello:
+    get:
+      responses:
+        "200":
+          description: Say hello
+          content:
+            application/json:
+              schema:
+                type: string
+  /world:
+    get:
+      responses:
+        "200":
+          description: OK
+          content:
+            '*/*':
+              schema:
+                type: string
+----
+
+=== Using Swagger UI
+
+Swagger UI is included by default when running in `dev` or `test` mode, and can optionally added to `prod` mode.
+See <<openapi-swaggerui.adoc#use-swagger-ui-for-development,the Swagger UI>> Guide for more details.
+
+Navigate to link:http://localhost:8080/swagger-ui/[localhost:8080/swagger-ui/] and you will see the Swagger UI screen:
+
+image:reactive-routes-guide-screenshot01.png[alt=Swagger UI]
+
 == Conclusion
 
 This guide has introduced how you can use reactive routes to define an HTTP endpoint.

extensions/smallrye-openapi/deployment/src/test/java/io/quarkus/smallrye/openapi/test/vertx/OpenApiRoute.java

@@ -11,7 +11,7 @@
 @RouteBase(path = "resource", consumes = "application/json", produces = "application/json")
 public class OpenApiRoute {
 
-    @Route(methods = HttpMethod.GET)
+    @Route(path = "/", methods = HttpMethod.GET)
     public String root() {
         return "resource";
     }

integration-tests/main/src/test/java/io/quarkus/it/main/OpenApiTestCase.java

@@ -42,7 +42,7 @@ public void testOpenAPIJSON() throws Exception {
         JsonObject obj = parser.readObject();
         Assertions.assertNotNull(obj);
 
-        Assertions.assertEquals("3.0.1", obj.getString("openapi"));
+        Assertions.assertEquals("3.0.3", obj.getString("openapi"));
         Assertions.assertEquals("Generated API", obj.getJsonObject("info").getString("title"));
         Assertions.assertEquals("1.0", obj.getJsonObject("info").getString("version"));