Add support for OpenAPI schema generation

vertx-grpc-docs/pom.xml

@@ -92,7 +92,7 @@
               <artifactId>vertx-grpc-protoc-plugin2</artifactId>
               <version>${project.version}</version>
               <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
-              <options>grpc-client=true,grpc-service=true,grpc-io=true</options>
+              <options>grpc-client=true,grpc-service=true,grpc-io=true,openapi-json=true,openapi-yaml=true</options>
             </jvmMavenPlugin>
           </jvmMavenPlugins>
           <!--jvmMavenPlugins>

vertx-grpc-docs/src/main/asciidoc/plugin.adoc

@@ -165,12 +165,160 @@ By default, the plugin generates both client and service files. If you need only
 - _[--]grpc-transcoding[=true/false]_: whether to generate transcoding options for methods with HTTP annotations
 - _[--]vertx-codegen[=true/false]_: whether to add Vert.x annotations to the generated classes (`@VertxGen`) By default, this is disabled
 - _[--]service-prefix[=Your Name]_: generate service classes with a prefix. For example, if you set it to `MyService`, the generated service class will be `MyServiceGreeterService` instead of `GreeterService`.
+- _[--]schema-output-format[=openapi-json+openapi-yaml]_: generate OpenAPI specification files. Use `openapi-json` for JSON format, `openapi-yaml` for YAML format, or combine both with `+` (e.g., `openapi-json+openapi-yaml`). Not generated by default.
+- _[--]schema-allow-merge[=true/false]_: when generating OpenAPI specs, merge all services into a single file (`openapi.json`/`openapi.yaml`). When set to `false`, generates separate files per service (`ServiceName-openapi.json`/`ServiceName-openapi.yaml`). Default is `true`.
+- _[--]schema-config[=/path/to/config.yaml]_: path to an OpenAPI configuration file (YAML or JSON) that customizes the generated specification. The config file can override info, servers, security, tags, externalDocs, and add securitySchemes. See <<openapi-configuration-file>> for details.
 
 * [--] This means the argument can be prefixed with `--` when used as JVM arguments, but should be used without `--` when specified in the options tag. If possible, users should use plugin options as a more universal protoc plugin approach.
 * [=value] This means the argument can optionally specify a value. For boolean arguments (true/false), if no value is specified, the default is `true` when the argument is present. For string arguments like `service-prefix`, a value must be provided.
 
 If no specific generation options are provided, both client and service files will be generated by default. By default, all extensions (currently only 'http') are supported.
 
+=== OpenAPI Specification Generation
+
+The plugin can generate OpenAPI 3.0 specification files from your gRPC service definitions. This is useful when using <<grpc-transcoding,gRPC transcoding>> to expose your services as REST APIs.
+
+OpenAPI specs are generated for services that have HTTP annotations (`google.api.http`). Services and methods without HTTP annotations are skipped.
+
+= OpenAPI specification generation
+
+The plugin generates OpenAPI 3.0 specification files from your gRPC service definitions. This is useful when you use <<grpc-transcoding,gRPC transcoding>> to expose services as REST APIs.
+
+The plugin only generates specs for services with HTTP annotations (`google.api.http`).
+
+== Enabling OpenAPI generation
+
+To start generating specs, add the `schema-output-format` option to your plugin configuration:
+
+[source,xml]
+----
+<jvmMavenPlugin>
+  <groupId>io.vertx</groupId>
+  <artifactId>vertx-grpc-protoc-plugin2</artifactId>
+  <version>${vertx.version}</version>
+  <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
+  <options>grpc-client=true,grpc-service=true,schema-output-format=openapi-json+openapi-yaml</options>
+</jvmMavenPlugin>
+----
+
+== Output formats
+
+The plugin supports two formats:
+
+* `openapi-json`: Generates a `.json` file.
+* `openapi-yaml`: Generates a `.yaml` file.
+
+To generate both at once, combine them with a `+` symbol:
+`schema-output-format=openapi-json+openapi-yaml`
+
+== Merge vs split mode
+
+By default, the plugin combines all services into a single OpenAPI file (`openapi.json` or `openapi.yaml`). If you prefer a separate file for each service, set `schema-allow-merge` to `false`.
+
+=== Merge mode (default)
+All services are bundled into one file.
+
+[source]
+----
+schema-allow-merge=true
+----
+
+=== Split mode
+Each service gets its own file, such as `GreeterService-openapi.json` or `AnotherService-openapi.yaml`.
+
+[source]
+----
+schema-allow-merge=false
+----
+
+[[openapi-configuration-file]]
+== Configuration file
+
+You can customize the output by providing a YAML or JSON configuration file. This allows you to set or override these fields:
+
+* `info`: API metadata like title, version, and contact info.
+* `servers`: Target server URLs.
+* `security`: Global security requirements.
+* `tags`: Tag definitions.
+* `externalDocs`: Links to outside documentation.
+* `components.securitySchemes`: Security scheme definitions.
+
+.Example configuration (openapi-config.yaml)
+[source,yaml]
+----
+openapi: 3.0.0
+info:
+  title: My Greeting API
+  version: 2.0.0
+  description: A greeting service
+  contact:
+    name: API Support
+    email: support@example.com
+servers:
+  - url: https://api.example.com
+    description: Production
+security:
+  - bearerAuth: []
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+----
+
+=== Using the configuration file
+
+[source,xml]
+----
+<jvmMavenPlugin>
+  <groupId>io.vertx</groupId>
+  <artifactId>vertx-grpc-protoc-plugin2</artifactId>
+  <version>${vertx.version}</version>
+  <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
+  <options>schema-output-format=openapi-json,schema-config=${project.basedir}/openapi-config.yaml</options>
+</jvmMavenPlugin>
+----
+
+The plugin merges your configuration with the generated spec using these rules:
+
+1. Values in `info`, `servers`, `security`, `tags`, and `externalDocs` *replace* whatever the plugin generates.
+2. Values in `components.securitySchemes` are *added* to the generated schemas.
+3. The plugin always preserves the generated `paths` and `components.schemas`. Your config file cannot override these.
+
+== Example
+
+If you have a proto file with HTTP annotations like this:
+
+[source,proto]
+----
+syntax = "proto3";
+import "google/api/http.proto";
+option java_package = "examples";
+
+service Greeter {
+  rpc SayHello (HelloRequest) returns (HelloReply) {
+    option (google.api.http) = {
+      post: "/v1/hello"
+      body: "*"
+      additional_bindings {
+        get: "/v1/hello/{name}"
+      }
+    };
+  }
+}
+
+message HelloRequest {
+  string name = 1;
+}
+
+message HelloReply {
+  string message = 1;
+}
+----
+
+The plugin produces an OpenAPI spec for the `/v1/hello` endpoints, including the request and response schemas. You can find the output in the protobuf output root folder.
+
 If you're using Gradle you need to add the plugin:
 
 [source,groovy]

vertx-grpc-docs/src/main/java/examples/grpc/openapi.json

@@ -0,0 +1,88 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "examples.grpc gRPC API",
+    "version": "1.0.0",
+    "description": "OpenAPI specification generated from gRPC service definitions with HTTP transcoding"
+  },
+  "servers": [
+    {
+      "url": "http://localhost:8080",
+      "description": "gRPC server"
+    }
+  ],
+  "paths": {
+    "/v1/hello/{name}": {
+      "GET": {
+        "summary": "SayHello",
+        "description": "",
+        "operationId": "sayHello",
+        "tags": [""],
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HelloReply"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "Error response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GrpcError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+  },
+  "components": {
+    "schemas": {
+      "HelloRequest": {
+        "type": "object",
+        "description": "Protobuf message type: .examples.grpc.HelloRequest",
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+        }
+      },
+      "HelloReply": {
+        "type": "object",
+        "description": "Protobuf message type: .examples.grpc.HelloReply",
+        "properties": {
+          "message": {
+            "type": "string"
+          },
+        }
+      },
+      "GrpcError": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "integer",
+            "description": "gRPC status code"
+          },
+          "message": {
+            "type": "string",
+            "description": "Error message"
+          },
+          "details": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Additional error details"
+          }
+        }
+      }
+    }
+  }
+}

vertx-grpc-docs/src/main/java/examples/grpc/openapi.yaml

@@ -0,0 +1,57 @@
+openapi: 3.0.0
+info:
+  title: examples.grpc gRPC API
+  version: 1.0.0
+  description: OpenAPI specification generated from gRPC service definitions with HTTP transcoding
+servers:
+  - url: http://localhost:8080
+    description: gRPC server
+paths:
+  /v1/hello/{name}:
+    GET:
+      summary: SayHello
+      description: 
+      operationId: sayHello
+      tags:
+        - 
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HelloReply'
+        default:
+          description: Error response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GrpcError'
+components:
+  schemas:
+    HelloRequest:
+      type: object
+      description: Protobuf message type .examples.grpc.HelloRequest
+      properties:
+        name:
+          type: string
+    HelloReply:
+      type: object
+      description: Protobuf message type .examples.grpc.HelloReply
+      properties:
+        message:
+          type: string
+    GrpcError:
+      type: object
+      properties:
+        code:
+          type: integer
+          description: gRPC status code
+        message:
+          type: string
+          description: Error message
+        details:
+          type: array
+          items:
+            type: object
+          description: Additional error details

vertx-grpc-it/pom.xml

@@ -89,6 +89,11 @@
       <artifactId>testcontainers</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>io.vertx</groupId>
+      <artifactId>vertx-openapi</artifactId>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 
   <build>
@@ -136,7 +141,7 @@
               <artifactId>vertx-grpc-protoc-plugin2</artifactId>
               <version>${project.version}</version>
               <mainClass>io.vertx.grpc.plugin.VertxGrpcGenerator</mainClass>
-              <options>grpc-client=true,grpc-service=true,grpc-io=true</options>
+              <options>grpc-client=true,grpc-service=true,grpc-io=true,schema-output-format=openapi-json+openapi-yaml,schema-config=${project.basedir}/src/test/resources/openapi-config.yaml</options>
             </jvmMavenPlugin>
           </jvmMavenPlugins>
         </configuration>