diff --git a/vertx-grpc-docs/pom.xml b/vertx-grpc-docs/pom.xml
index 0867932e..f68d0d87 100644
--- a/vertx-grpc-docs/pom.xml
+++ b/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>
diff --git a/vertx-grpc-docs/src/main/asciidoc/plugin.adoc b/vertx-grpc-docs/src/main/asciidoc/plugin.adoc
index cea0d20f..a4969c1b 100644
--- a/vertx-grpc-docs/src/main/asciidoc/plugin.adoc
+++ b/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]
diff --git a/vertx-grpc-docs/src/main/java/examples/grpc/openapi.json b/vertx-grpc-docs/src/main/java/examples/grpc/openapi.json
new file mode 100644
index 00000000..b616560d
--- /dev/null
+++ b/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"
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/vertx-grpc-docs/src/main/java/examples/grpc/openapi.yaml b/vertx-grpc-docs/src/main/java/examples/grpc/openapi.yaml
new file mode 100644
index 00000000..9def830c
--- /dev/null
+++ b/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
diff --git a/vertx-grpc-it/pom.xml b/vertx-grpc-it/pom.xml
index a3b0f3a0..c6737124 100644
--- a/vertx-grpc-it/pom.xml
+++ b/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>
diff --git a/vertx-grpc-it/src/test/java/io/vertx/grpc/it/SchemaGenerationTest.java b/vertx-grpc-it/src/test/java/io/vertx/grpc/it/SchemaGenerationTest.java
new file mode 100644
index 00000000..c36f0a73
--- /dev/null
+++ b/vertx-grpc-it/src/test/java/io/vertx/grpc/it/SchemaGenerationTest.java
@@ -0,0 +1,294 @@
+/*
+ * Copyright (c) 2011-2024 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+package io.vertx.grpc.it;
+
+import io.vertx.core.http.HttpMethod;
+import io.vertx.core.json.JsonObject;
+import io.vertx.ext.unit.junit.VertxUnitRunner;
+import io.vertx.openapi.contract.OpenAPIContract;
+import io.vertx.openapi.contract.Operation;
+import io.vertx.openapi.contract.Path;
+import io.vertx.tests.common.GrpcTestBase;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import java.io.File;
+import java.util.*;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+
+import static org.junit.Assert.*;
+
+/**
+ * Integration tests for OpenAPI generation through the protoc plugin. Validates that generated OpenAPI specifications are valid and contain the expected paths, operations, and
+ * schemas from proto files with HTTP transcoding annotations.
+ */
+@RunWith(VertxUnitRunner.class)
+public class SchemaGenerationTest extends GrpcTestBase {
+
+  private static final String GENERATED_SOURCES_PATH = "target/generated-test-sources/protobuf/";
+  private static final String OPENAPI_JSON = GENERATED_SOURCES_PATH + "openapi.json";
+  private static final String OPENAPI_YAML = GENERATED_SOURCES_PATH + "openapi.yaml";
+
+  @Test
+  public void testOpenApiJsonFileExists() {
+    File jsonFile = new File(OPENAPI_JSON);
+    assertTrue("openapi.json should exist in generated sources", jsonFile.exists());
+    assertTrue("openapi.json should not be empty", jsonFile.length() > 0);
+  }
+
+  @Test
+  public void testOpenApiYamlFileExists() {
+    File yamlFile = new File(OPENAPI_YAML);
+    assertTrue("openapi.yaml should exist in generated sources", yamlFile.exists());
+    assertTrue("openapi.yaml should not be empty", yamlFile.length() > 0);
+  }
+
+  @Test
+  public void testOpenApiJsonIsValid() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON)
+      .expecting(Objects::nonNull)
+      .await(20, TimeUnit.SECONDS);
+    assertNotNull("Contract should be parsed successfully", contract);
+  }
+
+  @Test
+  public void testOpenApiYamlIsValid() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_YAML)
+      .expecting(Objects::nonNull)
+      .await(20, TimeUnit.SECONDS);
+    assertNotNull("Contract should be parsed successfully", contract);
+  }
+
+  @Test
+  public void testOpenApiContainsPaths() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    List<Path> paths = contract.getPaths();
+    assertFalse("Contract should contain paths", paths.isEmpty());
+
+    Set<String> pathStrings = paths.stream()
+      .map(Path::getName)
+      .collect(Collectors.toSet());
+
+    // Expected paths from helloworld.proto HTTP annotations
+    Set<String> expectedPaths = new HashSet<>(Arrays.asList(
+      "/v1/hello/{name}",
+      "/v1/hello",
+      "/v2/hello",
+      "/v2/hello/{name}",
+      "/v1/hello/custom/{name}",
+      "/v1/rooms/{room}/messages/{message}",
+      "/v1/hello/body",
+      "/v1/hello/body/response"
+    ));
+
+    for (String expectedPath : expectedPaths) {
+      assertTrue("Contract should contain path: " + expectedPath, pathStrings.contains(expectedPath));
+    }
+  }
+
+  @Test
+  public void testOpenApiContainsOperations() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    List<Operation> operations = contract.operations();
+    assertFalse("Contract should contain operations", operations.isEmpty());
+
+    Set<String> operationIds = operations.stream()
+      .map(Operation::getOperationId)
+      .collect(Collectors.toSet());
+
+    // Expected operation IDs from helloworld.proto
+    Set<String> expectedOperationIds = new HashSet<>(Arrays.asList(
+      "sayHello",
+      "sayHello_post", // additional binding for POST /v1/hello
+      "sayHelloAgain",
+      "sayHelloAgain_get", // additional binding for GET /v2/hello/{name}
+      "sayHelloCustom",
+      "sayHelloNested",
+      "sayHelloWithBody",
+      "sayHelloWithResponseBOdy"
+    ));
+
+    for (String expectedOpId : expectedOperationIds) {
+      assertTrue("Contract should contain operation: " + expectedOpId, operationIds.contains(expectedOpId));
+    }
+  }
+
+  @Test
+  public void testOpenApiOperationsByPath() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    // Verify GET /v1/hello/{name} - primary binding
+    Operation getHello = contract.findOperation("/v1/hello/test", HttpMethod.GET);
+    assertNotNull("GET /v1/hello/{name} should exist", getHello);
+    assertEquals("sayHello", getHello.getOperationId());
+
+    // Verify POST /v1/hello - additional binding (gets _post suffix)
+    Operation postHello = contract.findOperation("/v1/hello", HttpMethod.POST);
+    assertNotNull("POST /v1/hello should exist", postHello);
+    assertEquals("sayHello_post", postHello.getOperationId());
+
+    // Verify POST /v2/hello - primary binding
+    Operation postHelloAgain = contract.findOperation("/v2/hello", HttpMethod.POST);
+    assertNotNull("POST /v2/hello should exist", postHelloAgain);
+    assertEquals("sayHelloAgain", postHelloAgain.getOperationId());
+
+    // Verify GET /v2/hello/{name} - additional binding (gets _get suffix)
+    Operation getHelloAgain = contract.findOperation("/v2/hello/world", HttpMethod.GET);
+    assertNotNull("GET /v2/hello/{name} should exist", getHelloAgain);
+    assertEquals("sayHelloAgain_get", getHelloAgain.getOperationId());
+
+    // Verify POST /v1/hello/body (with body annotation)
+    Operation postHelloWithBody = contract.findOperation("/v1/hello/body", HttpMethod.POST);
+    assertNotNull("POST /v1/hello/body should exist", postHelloWithBody);
+    assertEquals("sayHelloWithBody", postHelloWithBody.getOperationId());
+  }
+
+  @Test
+  public void testOpenApiContainsSchemas() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    List<Operation> operations = contract.operations();
+    assertFalse("Contract should have operations referencing schemas", operations.isEmpty());
+  }
+
+  @Test
+  public void testOpenApiJsonAndYamlEquivalent() throws Exception {
+    OpenAPIContract jsonContract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+    OpenAPIContract yamlContract = OpenAPIContract.from(vertx, OPENAPI_YAML).await(20, TimeUnit.SECONDS);
+
+    // Both should have the same paths
+    assertEquals("JSON and YAML should have same number of paths",
+      jsonContract.getPaths().size(),
+      yamlContract.getPaths().size()
+    );
+
+    // Both should have the same operations
+    assertEquals("JSON and YAML should have same number of operations",
+      jsonContract.operations().size(),
+      yamlContract.operations().size()
+    );
+
+    // Verify same path names
+    Set<String> jsonPaths = jsonContract.getPaths().stream().map(Path::getName).collect(Collectors.toSet());
+    Set<String> yamlPaths = yamlContract.getPaths().stream().map(Path::getName).collect(Collectors.toSet());
+
+    assertEquals("JSON and YAML should have identical paths", jsonPaths, yamlPaths);
+  }
+
+  @Test
+  public void testOpenApiOperationsHaveGreeterTag() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    List<Operation> operations = contract.operations();
+
+    for (Operation op : operations) {
+      List<String> tags = op.getTags();
+      assertNotNull("Operation " + op.getOperationId() + " should have tags", tags);
+      assertTrue("Operation " + op.getOperationId() + " should have Greeter tag", tags.contains("Greeter"));
+    }
+  }
+
+  @Test
+  public void testOpenApiOperationById() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    // Get operations by their operation ID
+    Operation sayHello = contract.operation("sayHello");
+    assertNotNull("Operation 'sayHello' should exist", sayHello);
+
+    Operation sayHelloAgain = contract.operation("sayHelloAgain");
+    assertNotNull("Operation 'sayHelloAgain' should exist", sayHelloAgain);
+
+    Operation sayHelloWithBody = contract.operation("sayHelloWithBody");
+    assertNotNull("Operation 'sayHelloWithBody' should exist", sayHelloWithBody);
+  }
+
+  @Test
+  public void testOpenApiRawContractStructure() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+
+    // Verify raw contract has expected structure
+    JsonObject rawContract = contract.getRawContract();
+    assertNotNull("Raw contract should not be null", rawContract);
+
+    // Verify openapi version
+    assertEquals("OpenAPI version should be 3.0.0", "3.0.0", rawContract.getString("openapi"));
+
+    // Verify paths section exists
+    JsonObject paths = rawContract.getJsonObject("paths");
+    assertNotNull("Paths section should exist", paths);
+    assertFalse("Paths should not be empty", paths.isEmpty());
+
+    // Verify components/schemas section exists
+    JsonObject components = rawContract.getJsonObject("components");
+    assertNotNull("Components section should exist", components);
+    JsonObject schemas = components.getJsonObject("schemas");
+    assertNotNull("Schemas section should exist", schemas);
+
+    // Verify expected schemas exist
+    assertTrue("HelloRequest schema should exist", schemas.containsKey("HelloRequest"));
+    assertTrue("HelloReply schema should exist", schemas.containsKey("HelloReply"));
+    assertTrue("GrpcError schema should exist", schemas.containsKey("GrpcError"));
+  }
+
+  @Test
+  public void testOpenApiConfigFileApplied() throws Exception {
+    OpenAPIContract contract = OpenAPIContract.from(vertx, OPENAPI_JSON).await(20, TimeUnit.SECONDS);
+    JsonObject rawContract = contract.getRawContract();
+
+    // Verify info section from config file
+    JsonObject info = rawContract.getJsonObject("info");
+    assertNotNull("Info section should exist", info);
+    assertEquals("Title should be from config", "Custom Greeting API", info.getString("title"));
+    assertEquals("Version should be from config", "2.0.0", info.getString("version"));
+    assertEquals("Description should be from config",
+      "A custom greeting service with full configuration", info.getString("description"));
+
+    // Verify contact from config
+    JsonObject contact = info.getJsonObject("contact");
+    assertNotNull("Contact should exist from config", contact);
+    assertEquals("Test Support", contact.getString("name"));
+    assertEquals("test@example.com", contact.getString("email"));
+
+    // Verify servers from config
+    var servers = rawContract.getJsonArray("servers");
+    assertNotNull("Servers should exist from config", servers);
+    assertEquals("Should have 2 servers from config", 2, servers.size());
+    assertEquals("https://api.example.com", servers.getJsonObject(0).getString("url"));
+    assertEquals("https://staging.example.com", servers.getJsonObject(1).getString("url"));
+
+    // Verify security from config
+    var security = rawContract.getJsonArray("security");
+    assertNotNull("Security should exist from config", security);
+    assertFalse("Security should not be empty", security.isEmpty());
+
+    // Verify externalDocs from config
+    JsonObject externalDocs = rawContract.getJsonObject("externalDocs");
+    assertNotNull("ExternalDocs should exist from config", externalDocs);
+    assertEquals("External documentation", externalDocs.getString("description"));
+    assertEquals("https://docs.example.com", externalDocs.getString("url"));
+
+    // Verify tags from config
+    var tags = rawContract.getJsonArray("tags");
+    assertNotNull("Tags should exist from config", tags);
+    assertEquals(1, tags.size());
+    assertEquals("Greeter", tags.getJsonObject(0).getString("name"));
+    assertEquals("Greeting operations for testing", tags.getJsonObject(0).getString("description"));
+
+    // Verify securitySchemes from config were merged into components
+    JsonObject securitySchemes = rawContract.getJsonObject("components").getJsonObject("securitySchemes");
+    assertNotNull("SecuritySchemes should exist from config", securitySchemes);
+    assertTrue("bearerAuth scheme should exist", securitySchemes.containsKey("bearerAuth"));
+  }
+}
diff --git a/vertx-grpc-it/src/test/proto/streaming.proto b/vertx-grpc-it/src/test/proto/streaming.proto
index 598787d8..400f242b 100644
--- a/vertx-grpc-it/src/test/proto/streaming.proto
+++ b/vertx-grpc-it/src/test/proto/streaming.proto
@@ -19,4 +19,4 @@ message Item {
 }
 
 message Empty {
-}
\ No newline at end of file
+}
diff --git a/vertx-grpc-it/src/test/resources/openapi-config.yaml b/vertx-grpc-it/src/test/resources/openapi-config.yaml
new file mode 100644
index 00000000..3b2a6287
--- /dev/null
+++ b/vertx-grpc-it/src/test/resources/openapi-config.yaml
@@ -0,0 +1,27 @@
+openapi: 3.0.0
+info:
+  title: Custom Greeting API
+  version: 2.0.0
+  description: A custom greeting service with full configuration
+  contact:
+    name: Test Support
+    email: test@example.com
+servers:
+  - url: https://api.example.com
+    description: Production server
+  - url: https://staging.example.com
+    description: Staging server
+security:
+  - bearerAuth: []
+tags:
+  - name: Greeter
+    description: Greeting operations for testing
+externalDocs:
+  description: External documentation
+  url: https://docs.example.com
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
diff --git a/vertx-grpc-protoc-plugin2/pom.xml b/vertx-grpc-protoc-plugin2/pom.xml
index 23fe045d..9b7c06b6 100644
--- a/vertx-grpc-protoc-plugin2/pom.xml
+++ b/vertx-grpc-protoc-plugin2/pom.xml
@@ -49,6 +49,11 @@
       <artifactId>picocli</artifactId>
       <version>4.7.5</version>
     </dependency>
+    <dependency>
+      <groupId>io.swagger.core.v3</groupId>
+      <artifactId>swagger-core</artifactId>
+      <version>2.2.28</version>
+    </dependency>
   </dependencies>
 
   <build>
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/VertxGrpcGenerator.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/VertxGrpcGenerator.java
index 5ee6cb9c..fe74830e 100644
--- a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/VertxGrpcGenerator.java
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/VertxGrpcGenerator.java
@@ -7,6 +7,7 @@
 import com.google.protobuf.GeneratedMessage;
 import com.google.protobuf.compiler.PluginProtos;
 import io.vertx.grpc.plugin.descriptors.ServiceDescriptor;
+import io.vertx.grpc.plugin.generation.SchemaOutputFormat;
 import io.vertx.grpc.plugin.generation.*;
 import io.vertx.grpc.plugin.generation.generators.*;
 import io.vertx.grpc.plugin.protoc.ProtocRequestConverter;
@@ -85,10 +86,17 @@ private static PluginProtos.CodeGeneratorResponse processRequest(PluginProtos.Co
           DescriptorProtos.ServiceDescriptorProto serviceProto = fileProto.getService(serviceIndex);
           ServiceDescriptor service = converter.convertService(serviceProto, fileProto, serviceIndex);
           services.add(service);
+
+          // Pre-convert message types for OpenAPI generation
+          for (int methodIndex = 0; methodIndex < serviceProto.getMethodCount(); methodIndex++) {
+            DescriptorProtos.MethodDescriptorProto methodProto = serviceProto.getMethod(methodIndex);
+            converter.convertMessage(methodProto.getInputType());
+            converter.convertMessage(methodProto.getOutputType());
+          }
         }
       }
 
-      List<PluginProtos.CodeGeneratorResponse.File> generatedFiles = generateCode(services, options);
+      List<PluginProtos.CodeGeneratorResponse.File> generatedFiles = generateCode(services, options, converter);
 
       int featureMask = supportedFeatures.stream()
         .map(PluginProtos.CodeGeneratorResponse.Feature::getNumber)
@@ -125,8 +133,29 @@ private static GenerationOptions parseOptions(String parameter) {
       .setGenerateVertxGeneratorAnnotations(getBooleanParam(params, "vertx-codegen", false))
       .setServicePrefix(params.getOrDefault("service-prefix", ""));
 
+    // Parse schema output formats: schema-output-format=openapi-json+openapi-yaml or schema-output-format=openapi-json
+    String schemaValue = params.get("schema-output-format");
+    if (schemaValue != null && !schemaValue.isEmpty()) {
+      for (String format : schemaValue.split("\\+")) {
+        SchemaOutputFormat schemaOutputFormat = SchemaOutputFormat.fromValue(format.trim());
+        if (schemaOutputFormat != null) {
+          options.addSchemaOutputFormat(schemaOutputFormat);
+        }
+      }
+    }
+
+    // Parse schema merge option: schema-allow-merge=true (default) combines all services into one file
+    options.setSchemaAllowMerge(getBooleanParam(params, "schema-allow-merge", true));
+
+    // Parse schema config file option: schema-config=/path/to/openapi-config.yaml
+    String schemaConfigFile = params.get("schema-config");
+    if (schemaConfigFile != null && !schemaConfigFile.isEmpty()) {
+      options.setSchemaConfigFile(schemaConfigFile);
+    }
+
     // If nothing specified, default to generate client and generate service
-    if (!options.isGenerateClient() && !options.isGenerateService() && !options.isGenerateIo()) {
+    if (!options.isGenerateClient() && !options.isGenerateService() && !options.isGenerateIo()
+        && !options.isGenerateOpenApi()) {
       options.setGenerateClient(true).setGenerateService(true);
     }
 
@@ -156,7 +185,7 @@ private static boolean getBooleanParam(Map<String, String> params, String key, b
     return "true".equalsIgnoreCase(value) || "1".equals(value);
   }
 
-  private static List<PluginProtos.CodeGeneratorResponse.File> generateCode(List<ServiceDescriptor> services, GenerationOptions options) {
+  private static List<PluginProtos.CodeGeneratorResponse.File> generateCode(List<ServiceDescriptor> services, GenerationOptions options, ProtocRequestConverter converter) {
     List<PluginProtos.CodeGeneratorResponse.File> allFiles = new ArrayList<>();
 
     // Group services by package for generation
@@ -166,7 +195,7 @@ private static List<PluginProtos.CodeGeneratorResponse.File> generateCode(List<S
       String packageName = entry.getKey();
       List<ServiceDescriptor> packageServices = entry.getValue();
 
-      GenerationContext context = new GenerationContext(packageName, "", packageServices, options);
+      GenerationContext context = new GenerationContext(packageName, "", packageServices, options, converter.getMessageDescriptors());
 
       Map<GenerationType, List<CodeGenerator>> generators = new HashMap<>();
 
@@ -176,6 +205,7 @@ private static List<PluginProtos.CodeGeneratorResponse.File> generateCode(List<S
       generators.put(GenerationType.SERVICE, List.of(new GrpcServiceGenerator()));
       generators.put(GenerationType.GRPC_SERVICE, List.of(new GrpcGrpcServiceGenerator()));
       generators.put(GenerationType.GRPC_IO, List.of(new GrpcIoGenerator()));
+      generators.put(GenerationType.OPENAPI, List.of(new SchemaGenerator()));
 
       CodeGenerationEngine engine = new CodeGenerationEngine(generators);
       GenerationResult result = engine.generate(context);
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/descriptors/MessageDescriptor.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/descriptors/MessageDescriptor.java
new file mode 100644
index 00000000..e3b62a72
--- /dev/null
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/descriptors/MessageDescriptor.java
@@ -0,0 +1,174 @@
+package io.vertx.grpc.plugin.descriptors;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Represents metadata and configuration for a Protocol Buffer message type.
+ */
+public class MessageDescriptor {
+
+  public static final String DEFAULT_NAME = "";
+  public static final String DEFAULT_FULL_NAME = "";
+  public static final String DEFAULT_JAVA_TYPE = "";
+
+  private String name;
+  private String fullName;
+  private String javaType;
+  private List<FieldDescriptor> fields;
+  private Map<String, Object> metadata;
+
+  public MessageDescriptor() {
+    this.name = DEFAULT_NAME;
+    this.fullName = DEFAULT_FULL_NAME;
+    this.javaType = DEFAULT_JAVA_TYPE;
+    this.fields = new ArrayList<>();
+    this.metadata = new HashMap<>();
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public MessageDescriptor setName(String name) {
+    this.name = name;
+    return this;
+  }
+
+  public String getFullName() {
+    return fullName;
+  }
+
+  public MessageDescriptor setFullName(String fullName) {
+    this.fullName = fullName;
+    return this;
+  }
+
+  public String getJavaType() {
+    return javaType;
+  }
+
+  public MessageDescriptor setJavaType(String javaType) {
+    this.javaType = javaType;
+    return this;
+  }
+
+  public List<FieldDescriptor> getFields() {
+    return new ArrayList<>(fields);
+  }
+
+  public MessageDescriptor addField(FieldDescriptor field) {
+    this.fields.add(field);
+    return this;
+  }
+
+  public MessageDescriptor setFields(List<FieldDescriptor> fields) {
+    this.fields = new ArrayList<>(fields);
+    return this;
+  }
+
+  public Map<String, Object> getMetadata() {
+    return new HashMap<>(metadata);
+  }
+
+  public MessageDescriptor addMetadata(String key, Object value) {
+    this.metadata.put(key, value);
+    return this;
+  }
+
+  public MessageDescriptor setMetadata(Map<String, Object> metadata) {
+    this.metadata = new HashMap<>(metadata);
+    return this;
+  }
+
+  /**
+   * Represents metadata for a single field within a Protocol Buffer message.
+   */
+  public static class FieldDescriptor {
+    private String name;
+    private String jsonName;
+    private String type;
+    private String javaType;
+    private boolean repeated;
+    private boolean required;
+    private int number;
+    private String documentation;
+
+    public FieldDescriptor() {
+    }
+
+    public String getName() {
+      return name;
+    }
+
+    public FieldDescriptor setName(String name) {
+      this.name = name;
+      return this;
+    }
+
+    public String getJsonName() {
+      return jsonName;
+    }
+
+    public FieldDescriptor setJsonName(String jsonName) {
+      this.jsonName = jsonName;
+      return this;
+    }
+
+    public String getType() {
+      return type;
+    }
+
+    public FieldDescriptor setType(String type) {
+      this.type = type;
+      return this;
+    }
+
+    public String getJavaType() {
+      return javaType;
+    }
+
+    public FieldDescriptor setJavaType(String javaType) {
+      this.javaType = javaType;
+      return this;
+    }
+
+    public boolean isRepeated() {
+      return repeated;
+    }
+
+    public FieldDescriptor setRepeated(boolean repeated) {
+      this.repeated = repeated;
+      return this;
+    }
+
+    public boolean isRequired() {
+      return required;
+    }
+
+    public FieldDescriptor setRequired(boolean required) {
+      this.required = required;
+      return this;
+    }
+
+    public int getNumber() {
+      return number;
+    }
+
+    public FieldDescriptor setNumber(int number) {
+      this.number = number;
+      return this;
+    }
+
+    public String getDocumentation() {
+      return documentation;
+    }
+
+    public FieldDescriptor setDocumentation(String documentation) {
+      this.documentation = documentation;
+      return this;
+    }
+  }
+}
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/CodeGenerationEngine.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/CodeGenerationEngine.java
index bc7774f5..0e0ede6f 100644
--- a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/CodeGenerationEngine.java
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/CodeGenerationEngine.java
@@ -80,6 +80,9 @@ private List<GenerationType> determineGrpcTypes(GenerationOptions options) {
     if (options.isGenerateIo()) {
       types.add(GenerationType.GRPC_IO);
     }
+    if (options.isGenerateOpenApi()) {
+      types.add(GenerationType.OPENAPI);
+    }
 
     return types;
   }
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationContext.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationContext.java
index 873cbbfc..455fe4bf 100644
--- a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationContext.java
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationContext.java
@@ -1,7 +1,9 @@
 package io.vertx.grpc.plugin.generation;
 
+import io.vertx.grpc.plugin.descriptors.MessageDescriptor;
 import io.vertx.grpc.plugin.descriptors.ServiceDescriptor;
 
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -13,12 +15,18 @@ public class GenerationContext {
   private final GenerationOptions options;
   private final List<ServiceDescriptor> services;
   private final Map<String, Object> templateVariables = new HashMap<>();
+  private final Map<String, MessageDescriptor> messageDescriptors;
 
   public GenerationContext(String packageName, String outputDirectory, List<ServiceDescriptor> services, GenerationOptions options) {
+    this(packageName, outputDirectory, services, options, Collections.emptyMap());
+  }
+
+  public GenerationContext(String packageName, String outputDirectory, List<ServiceDescriptor> services, GenerationOptions options, Map<String, MessageDescriptor> messageDescriptors) {
     this.packageName = packageName;
     this.outputDirectory = outputDirectory;
     this.services = services;
     this.options = options;
+    this.messageDescriptors = messageDescriptors;
   }
 
   public String getPackageName() {
@@ -40,4 +48,8 @@ public List<ServiceDescriptor> getServices() {
   public Map<String, Object> getTemplateVariables() {
     return templateVariables;
   }
+
+  public Map<String, MessageDescriptor> getMessageDescriptors() {
+    return messageDescriptors;
+  }
 }
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationOptions.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationOptions.java
index 30b5cd59..02e845e1 100644
--- a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationOptions.java
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationOptions.java
@@ -1,5 +1,9 @@
 package io.vertx.grpc.plugin.generation;
 
+import java.util.Collections;
+import java.util.EnumSet;
+import java.util.Set;
+
 /**
  * Represents options for configuring code generation.
  * <p>
@@ -51,6 +55,9 @@ public class GenerationOptions {
   private boolean generateTranscoding;
   private boolean generateVertxGeneratorAnnotations;
   private String servicePrefix;
+  private Set<SchemaOutputFormat> schemaOutputFormats;
+  private boolean schemaAllowMerge;
+  private String schemaConfigFile;
 
   public GenerationOptions() {
     this.generateClient = DEFAULT_GENERATE_CLIENT;
@@ -59,6 +66,9 @@ public GenerationOptions() {
     this.generateTranscoding = DEFAULT_GENERATE_TRANSCODING;
     this.generateVertxGeneratorAnnotations = DEFAULT_GENERATE_VERTX_GENERATOR_ANNOTATIONS;
     this.servicePrefix = DEFAULT_SERVICE_PREFIX;
+    this.schemaOutputFormats = EnumSet.noneOf(SchemaOutputFormat.class);
+    this.schemaAllowMerge = true;
+    this.schemaConfigFile = null;
   }
 
   /**
@@ -180,4 +190,129 @@ public GenerationOptions setServicePrefix(String servicePrefix) {
     this.servicePrefix = servicePrefix;
     return this;
   }
+
+  /**
+   * Determines whether any OpenAPI format generation is enabled.
+   *
+   * @return true if at least one OpenAPI format is configured for generation, false otherwise.
+   */
+  public boolean isGenerateOpenApi() {
+    return !schemaOutputFormats.isEmpty();
+  }
+
+  /**
+   * Determines whether OpenAPI JSON spec generation is enabled.
+   *
+   * @return true if OpenAPI JSON generation is enabled, false otherwise.
+   */
+  public boolean isGenerateOpenApiJson() {
+    return schemaOutputFormats.contains(SchemaOutputFormat.OPEN_API_JSON);
+  }
+
+  /**
+   * Determines whether OpenAPI YAML spec generation is enabled.
+   *
+   * @return true if OpenAPI YAML generation is enabled, false otherwise.
+   */
+  public boolean isGenerateOpenApiYaml() {
+    return schemaOutputFormats.contains(SchemaOutputFormat.OPEN_API_YAML);
+  }
+
+  /**
+   * Returns the set of schema output formats configured for generation.
+   *
+   * @return an unmodifiable set of schema output formats
+   */
+  public Set<SchemaOutputFormat> getSchemaOutputFormats() {
+    return Collections.unmodifiableSet(schemaOutputFormats);
+  }
+
+  /**
+   * Sets the schema output formats to generate.
+   *
+   * @param formats the set of schema output formats to generate
+   * @return the current {@code GenerationOptions} instance to allow method chaining
+   */
+  public GenerationOptions setSchemaOutputFormats(Set<SchemaOutputFormat> formats) {
+    this.schemaOutputFormats = formats != null ? EnumSet.copyOf(formats) : EnumSet.noneOf(SchemaOutputFormat.class);
+    return this;
+  }
+
+  /**
+   * Adds a schema output format to generate.
+   *
+   * @param format the schema output format to add
+   * @return the current {@code GenerationOptions} instance to allow method chaining
+   */
+  public GenerationOptions addSchemaOutputFormat(SchemaOutputFormat format) {
+    if (format != null) {
+      this.schemaOutputFormats.add(format);
+    }
+    return this;
+  }
+
+  /**
+   * Determines whether OpenAPI specs should be merged into a single file.
+   *
+   * @return true if specs should be merged, false for per-service files
+   */
+  public boolean isSchemaAllowMerge() {
+    return schemaAllowMerge;
+  }
+
+  /**
+   * Sets whether OpenAPI specs should be merged into a single file.
+   *
+   * @param schemaAllowMerge true to merge all services into one file, false for per-service files
+   * @return the current {@code GenerationOptions} instance to allow method chaining
+   */
+  public GenerationOptions setSchemaAllowMerge(boolean schemaAllowMerge) {
+    this.schemaAllowMerge = schemaAllowMerge;
+    return this;
+  }
+
+  /**
+   * Returns the path to the OpenAPI configuration file.
+   * The configuration file should be a YAML or JSON file containing OpenAPI specification
+   * fields (info, servers, security, tags, externalDocs, etc.) that will be merged with
+   * the generated specification.
+   *
+   * @return the path to the configuration file, or null if not set
+   */
+  public String getSchemaConfigFile() {
+    return schemaConfigFile;
+  }
+
+  /**
+   * Sets the path to the OpenAPI configuration file.
+   * The configuration file should be a YAML or JSON file containing OpenAPI specification
+   * fields that will be merged with the generated specification.
+   *
+   * @param schemaConfigFile the path to the configuration file
+   * @return the current {@code GenerationOptions} instance to allow method chaining
+   */
+  public GenerationOptions setSchemaConfigFile(String schemaConfigFile) {
+    this.schemaConfigFile = schemaConfigFile;
+    return this;
+  }
+
+  /**
+   * Returns a string representation of this GenerationOptions instance, including all configuration fields.
+   *
+   * @return a string representation of this object
+   */
+  @Override
+  public String toString() {
+    return "GenerationOptions{" +
+      "generateClient=" + generateClient +
+      ", generateService=" + generateService +
+      ", generateIo=" + generateIo +
+      ", generateTranscoding=" + generateTranscoding +
+      ", generateVertxGeneratorAnnotations=" + generateVertxGeneratorAnnotations +
+      ", servicePrefix='" + servicePrefix + '\'' +
+      ", schemaOutputFormats=" + schemaOutputFormats +
+      ", schemaAllowMerge=" + schemaAllowMerge +
+      ", schemaConfigFile='" + schemaConfigFile + '\'' +
+      '}';
+  }
 }
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationType.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationType.java
index 74e7181f..4d3ad289 100644
--- a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationType.java
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/GenerationType.java
@@ -6,5 +6,6 @@ public enum GenerationType {
   GRPC_CLIENT,
   SERVICE,
   GRPC_SERVICE,
-  GRPC_IO
+  GRPC_IO,
+  OPENAPI
 }
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/SchemaOutputFormat.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/SchemaOutputFormat.java
new file mode 100644
index 00000000..e5397d41
--- /dev/null
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/SchemaOutputFormat.java
@@ -0,0 +1,60 @@
+package io.vertx.grpc.plugin.generation;
+
+/**
+ * Represents the available output formats for OpenAPI specification generation.
+ */
+public enum SchemaOutputFormat {
+  /**
+   * OpenAPI JSON format output (.json extension)
+   */
+  OPEN_API_JSON("openapi-json", "json"),
+
+  /**
+   * OpenAPI YAML format output (.yaml extension)
+   */
+  OPEN_API_YAML("openapi-yaml", "yaml");
+
+  private final String value;
+  private final String extension;
+
+  SchemaOutputFormat(String value, String extension) {
+    this.value = value;
+    this.extension = extension;
+  }
+
+  /**
+   * Returns the string value of this format used for CLI parameter parsing.
+   *
+   * @return the format value (e.g., "openapi-json" or "openapi-yaml")
+   */
+  public String getValue() {
+    return value;
+  }
+
+  /**
+   * Returns the file extension for this format.
+   *
+   * @return the file extension (e.g., "json" or "yaml")
+   */
+  public String getExtension() {
+    return extension;
+  }
+
+  /**
+   * Parses a string value to an SchemaOutputFormat enum.
+   *
+   * @param value the string value to parse
+   * @return the corresponding SchemaOutputFormat, or null if not found
+   */
+  public static SchemaOutputFormat fromValue(String value) {
+    if (value == null) {
+      return null;
+    }
+    for (SchemaOutputFormat format : values()) {
+      if (format.value.equalsIgnoreCase(value)) {
+        return format;
+      }
+    }
+    return null;
+  }
+}
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/generators/SchemaGenerator.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/generators/SchemaGenerator.java
new file mode 100644
index 00000000..69c263f2
--- /dev/null
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/generation/generators/SchemaGenerator.java
@@ -0,0 +1,131 @@
+package io.vertx.grpc.plugin.generation.generators;
+
+import io.swagger.v3.core.util.Json;
+import io.swagger.v3.core.util.Yaml;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.vertx.grpc.plugin.descriptors.ServiceDescriptor;
+import io.vertx.grpc.plugin.generation.*;
+import io.vertx.grpc.plugin.schema.SchemaConfigLoader;
+import io.vertx.grpc.plugin.schema.SchemaModelBuilder;
+
+import java.io.IOException;
+import java.util.*;
+
+/**
+ * Generator for OpenAPI specifications.
+ * <p>
+ * This generator uses the Swagger Core library to build an OpenAPI model programmatically from gRPC service definitions and serializes it to the requested formats (JSON, YAML, or
+ * both).
+ * <p>
+ * Supports two modes:
+ * <ul>
+ *   <li>Merge mode (default): All services combined into a single openapi.json/yaml file</li>
+ *   <li>Split mode: Each service gets its own ServiceName-openapi.json/yaml file</li>
+ * </ul>
+ * Files are always generated in the protobuf root folder.
+ */
+public class SchemaGenerator extends CodeGenerator {
+
+  public SchemaGenerator() {
+    super(GenerationType.OPENAPI);
+  }
+
+  @Override
+  public GenerationResult generate(GenerationContext context) {
+    List<GeneratedFile> files = new ArrayList<>();
+    Set<SchemaOutputFormat> formats = context.getOptions().getSchemaOutputFormats();
+
+    if (formats.isEmpty()) {
+      return GenerationResult.success(files);
+    }
+
+    try {
+      // Load config file if specified
+      OpenAPI config = loadConfig(context.getOptions().getSchemaConfigFile());
+
+      if (context.getOptions().isSchemaAllowMerge()) {
+        generateMergedSpec(context, formats, files, config);
+      } else {
+        generateSplitSpecs(context, formats, files, config);
+      }
+    } catch (Exception e) {
+      return GenerationResult.failure(List.of(
+        new GenerationError("Failed to generate OpenAPI spec: " + e.getMessage(), e, generationType)
+      ));
+    }
+
+    return GenerationResult.success(files);
+  }
+
+  /**
+   * Loads the OpenAPI configuration from a file if specified.
+   *
+   * @param configFile the path to the config file, or null
+   * @return the loaded OpenAPI config, or null if no config file specified
+   * @throws IOException if there's an error loading the config file
+   */
+  private OpenAPI loadConfig(String configFile) throws IOException {
+    if (configFile == null || configFile.isEmpty()) {
+      return null;
+    }
+    return SchemaConfigLoader.load(configFile);
+  }
+
+  private void generateMergedSpec(GenerationContext context, Set<SchemaOutputFormat> formats,
+    List<GeneratedFile> files, OpenAPI config) {
+    OpenAPI openAPI = SchemaModelBuilder.build(
+      context.getServices(),
+      context.getPackageName(),
+      context.getMessageDescriptors(),
+      config
+    );
+
+    if (openAPI == null) {
+      return;
+    }
+
+    for (SchemaOutputFormat format : formats) {
+      String content = serializeOpenApi(openAPI, format);
+      String fileName = "openapi." + format.getExtension();
+      // Empty relative path = protobuf root folder
+      GeneratedFile file = new GeneratedFile(fileName, "", content, generationType);
+      files.add(file);
+    }
+  }
+
+  private void generateSplitSpecs(GenerationContext context, Set<SchemaOutputFormat> formats,
+    List<GeneratedFile> files, OpenAPI config) {
+    for (ServiceDescriptor service : context.getServices()) {
+      if (service.getTranscodingMethods().isEmpty()) {
+        continue;
+      }
+
+      OpenAPI openAPI = SchemaModelBuilder.build(
+        Collections.singletonList(service),
+        context.getPackageName(),
+        context.getMessageDescriptors(),
+        config
+      );
+
+      if (openAPI == null) {
+        continue;
+      }
+
+      String serviceName = service.getName();
+      for (SchemaOutputFormat format : formats) {
+        String content = serializeOpenApi(openAPI, format);
+        String fileName = serviceName + "-openapi." + format.getExtension();
+        // Empty relative path = protobuf root folder
+        GeneratedFile file = new GeneratedFile(fileName, "", content, generationType);
+        files.add(file);
+      }
+    }
+  }
+
+  private String serializeOpenApi(OpenAPI openAPI, SchemaOutputFormat format) {
+    if (Objects.requireNonNull(format) == SchemaOutputFormat.OPEN_API_YAML) {
+      return Yaml.pretty(openAPI);
+    }
+    return Json.pretty(openAPI);
+  }
+}
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/protoc/ProtocRequestConverter.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/protoc/ProtocRequestConverter.java
index 532fadfa..e08e7af2 100644
--- a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/protoc/ProtocRequestConverter.java
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/protoc/ProtocRequestConverter.java
@@ -5,12 +5,12 @@
 import com.google.common.html.HtmlEscapers;
 import com.google.protobuf.DescriptorProtos;
 import com.google.protobuf.compiler.PluginProtos;
+import io.vertx.grpc.plugin.descriptors.MessageDescriptor;
 import io.vertx.grpc.plugin.descriptors.MethodDescriptor;
 import io.vertx.grpc.plugin.descriptors.ServiceDescriptor;
 import io.vertx.grpc.plugin.descriptors.TranscodingDescriptor;
 
-import java.util.Arrays;
-import java.util.List;
+import java.util.*;
 
 /**
  * Responsible for converting Protocol Buffers definitions into internal representations used for further processing or code generation. This class primarily focuses on
@@ -19,9 +19,30 @@
 public class ProtocRequestConverter {
 
   private final ProtobufTypeMapper typeMapper;
+  private final Map<String, DescriptorProtos.FileDescriptorProto> filesByName = new HashMap<>();
+  private final Map<String, MessageDescriptor> messagesByProtoType = new HashMap<>();
+  private final Map<String, DescriptorProtos.DescriptorProto> protoMessagesByType = new HashMap<>();
 
-  public ProtocRequestConverter(ProtobufTypeMapper typeMapper) {
+  public ProtocRequestConverter(ProtobufTypeMapper typeMapper, List<DescriptorProtos.FileDescriptorProto> files) {
     this.typeMapper = typeMapper;
+    // Index all files for lookup
+    for (DescriptorProtos.FileDescriptorProto file : files) {
+      filesByName.put(file.getName(), file);
+      // Index all messages in this file
+      for (DescriptorProtos.DescriptorProto message : file.getMessageTypeList()) {
+        indexMessage(message, file.getPackage(), "");
+      }
+    }
+  }
+
+  private void indexMessage(DescriptorProtos.DescriptorProto message, String protoPackage, String prefix) {
+    String protoTypeName = "." + protoPackage + "." + prefix + message.getName();
+    protoMessagesByType.put(protoTypeName, message);
+
+    // Index nested messages
+    for (DescriptorProtos.DescriptorProto nested : message.getNestedTypeList()) {
+      indexMessage(nested, protoPackage, prefix + message.getName() + ".");
+    }
   }
 
   /**
@@ -32,7 +53,148 @@ public ProtocRequestConverter(ProtobufTypeMapper typeMapper) {
    */
   public static ProtocRequestConverter create(PluginProtos.CodeGeneratorRequest request) {
     ProtobufTypeMapper typeMapper = new ProtobufTypeMapper(request.getProtoFileList());
-    return new ProtocRequestConverter(typeMapper);
+    return new ProtocRequestConverter(typeMapper, request.getProtoFileList());
+  }
+
+  /**
+   * Gets all collected message descriptors.
+   *
+   * @return a map of Java type names to MessageDescriptor objects
+   */
+  public Map<String, MessageDescriptor> getMessageDescriptors() {
+    return new HashMap<>(messagesByProtoType);
+  }
+
+  /**
+   * Converts a protobuf message type to a MessageDescriptor.
+   *
+   * @param protoTypeName the protobuf type name (e.g., ".mypackage.MyMessage")
+   * @return the MessageDescriptor or null if not found
+   */
+  public MessageDescriptor convertMessage(String protoTypeName) {
+    // Check cache first
+    if (messagesByProtoType.containsKey(protoTypeName)) {
+      return messagesByProtoType.get(protoTypeName);
+    }
+
+    DescriptorProtos.DescriptorProto messageProto = protoMessagesByType.get(protoTypeName);
+    if (messageProto == null) {
+      return null;
+    }
+
+    String javaType = typeMapper.toJavaTypeName(protoTypeName);
+    MessageDescriptor message = new MessageDescriptor()
+      .setName(messageProto.getName())
+      .setFullName(protoTypeName)
+      .setJavaType(javaType);
+
+    // Convert fields
+    for (DescriptorProtos.FieldDescriptorProto fieldProto : messageProto.getFieldList()) {
+      MessageDescriptor.FieldDescriptor field = convertField(fieldProto);
+      message.addField(field);
+    }
+
+    messagesByProtoType.put(protoTypeName, message);
+    return message;
+  }
+
+  private MessageDescriptor.FieldDescriptor convertField(DescriptorProtos.FieldDescriptorProto fieldProto) {
+    MessageDescriptor.FieldDescriptor field = new MessageDescriptor.FieldDescriptor()
+      .setName(fieldProto.getName())
+      .setNumber(fieldProto.getNumber())
+      .setRepeated(fieldProto.getLabel() == DescriptorProtos.FieldDescriptorProto.Label.LABEL_REPEATED)
+      .setRequired(fieldProto.getLabel() == DescriptorProtos.FieldDescriptorProto.Label.LABEL_REQUIRED);
+
+    // Set json_name
+    if (fieldProto.hasJsonName() && !fieldProto.getJsonName().isEmpty()) {
+      field.setJsonName(fieldProto.getJsonName());
+    } else {
+      // Default json_name is camelCase version of field name
+      field.setJsonName(toCamelCase(fieldProto.getName()));
+    }
+
+    // Determine type
+    String protoType = getProtoFieldType(fieldProto);
+    field.setType(protoType);
+
+    // Set Java type
+    if (fieldProto.getType() == DescriptorProtos.FieldDescriptorProto.Type.TYPE_MESSAGE ||
+        fieldProto.getType() == DescriptorProtos.FieldDescriptorProto.Type.TYPE_ENUM) {
+      field.setJavaType(typeMapper.toJavaTypeName(fieldProto.getTypeName()));
+    } else {
+      field.setJavaType(mapFieldTypeToJava(fieldProto.getType()));
+    }
+
+    return field;
+  }
+
+  private String getProtoFieldType(DescriptorProtos.FieldDescriptorProto fieldProto) {
+    switch (fieldProto.getType()) {
+      case TYPE_DOUBLE: return "double";
+      case TYPE_FLOAT: return "float";
+      case TYPE_INT64: return "int64";
+      case TYPE_UINT64: return "uint64";
+      case TYPE_INT32: return "int32";
+      case TYPE_FIXED64: return "fixed64";
+      case TYPE_FIXED32: return "fixed32";
+      case TYPE_BOOL: return "bool";
+      case TYPE_STRING: return "string";
+      case TYPE_BYTES: return "bytes";
+      case TYPE_UINT32: return "uint32";
+      case TYPE_SFIXED32: return "sfixed32";
+      case TYPE_SFIXED64: return "sfixed64";
+      case TYPE_SINT32: return "sint32";
+      case TYPE_SINT64: return "sint64";
+      case TYPE_MESSAGE: return fieldProto.getTypeName();
+      case TYPE_ENUM: return fieldProto.getTypeName();
+      default: return "unknown";
+    }
+  }
+
+  private String mapFieldTypeToJava(DescriptorProtos.FieldDescriptorProto.Type type) {
+    switch (type) {
+      case TYPE_DOUBLE: return "double";
+      case TYPE_FLOAT: return "float";
+      case TYPE_INT64:
+      case TYPE_UINT64:
+      case TYPE_FIXED64:
+      case TYPE_SFIXED64:
+      case TYPE_SINT64:
+        return "long";
+      case TYPE_INT32:
+      case TYPE_UINT32:
+      case TYPE_FIXED32:
+      case TYPE_SFIXED32:
+      case TYPE_SINT32:
+        return "int";
+      case TYPE_BOOL: return "boolean";
+      case TYPE_STRING: return "String";
+      case TYPE_BYTES: return "ByteString";
+      default: return "Object";
+    }
+  }
+
+  private String toCamelCase(String input) {
+    if (input == null || input.isEmpty()) {
+      return input;
+    }
+
+    StringBuilder result = new StringBuilder();
+    boolean capitalizeNext = false;
+
+    for (int i = 0; i < input.length(); i++) {
+      char c = input.charAt(i);
+      if (c == '_') {
+        capitalizeNext = true;
+      } else if (capitalizeNext) {
+        result.append(Character.toUpperCase(c));
+        capitalizeNext = false;
+      } else {
+        result.append(c);
+      }
+    }
+
+    return result.toString();
   }
 
   /**
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/schema/SchemaConfigLoader.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/schema/SchemaConfigLoader.java
new file mode 100644
index 00000000..d6556741
--- /dev/null
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/schema/SchemaConfigLoader.java
@@ -0,0 +1,119 @@
+package io.vertx.grpc.plugin.schema;
+
+import io.swagger.v3.core.util.Json;
+import io.swagger.v3.core.util.Yaml;
+import io.swagger.v3.oas.models.OpenAPI;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+
+/**
+ * Loads OpenAPI configuration from YAML or JSON files.
+ * <p>
+ * The configuration file should contain OpenAPI specification fields that will be merged
+ * with the generated specification. Supported fields include:
+ * <ul>
+ *   <li>info - API metadata (title, description, version, contact, license, termsOfService)</li>
+ *   <li>servers - Server URLs and descriptions</li>
+ *   <li>security - Global security requirements</li>
+ *   <li>tags - Tag definitions with descriptions</li>
+ *   <li>externalDocs - External documentation links</li>
+ *   <li>components.securitySchemes - Security scheme definitions</li>
+ * </ul>
+ * <p>
+ * Example YAML configuration:
+ * <pre>
+ * openapi: 3.0.0
+ * info:
+ *   title: My API
+ *   version: 2.0.0
+ *   description: My custom API description
+ *   contact:
+ *     name: Support
+ *     email: support@example.com
+ * servers:
+ *   - url: https://api.example.com
+ *     description: Production server
+ * security:
+ *   - bearerAuth: []
+ * components:
+ *   securitySchemes:
+ *     bearerAuth:
+ *       type: http
+ *       scheme: bearer
+ * </pre>
+ */
+public class SchemaConfigLoader {
+
+  /**
+   * Loads an OpenAPI configuration from a file.
+   * The file format is determined by the file extension (.yaml, .yml, or .json).
+   *
+   * @param filePath the path to the configuration file
+   * @return the parsed OpenAPI configuration, or null if the file doesn't exist or is empty
+   * @throws IOException if there's an error reading the file
+   * @throws IllegalArgumentException if the file format is not supported
+   */
+  public static OpenAPI load(String filePath) throws IOException {
+    if (filePath == null || filePath.isEmpty()) {
+      return null;
+    }
+
+    Path path = Paths.get(filePath);
+    if (!Files.exists(path)) {
+      throw new IOException("Schema config file not found: " + filePath);
+    }
+
+    String content = Files.readString(path);
+    if (content == null || content.trim().isEmpty()) {
+      return null;
+    }
+
+    String lowerPath = filePath.toLowerCase();
+    if (lowerPath.endsWith(".yaml") || lowerPath.endsWith(".yml")) {
+      return parseYaml(content);
+    } else if (lowerPath.endsWith(".json")) {
+      return parseJson(content);
+    } else {
+      // Try to detect format from content
+      String trimmed = content.trim();
+      if (trimmed.startsWith("{")) {
+        return parseJson(content);
+      } else {
+        return parseYaml(content);
+      }
+    }
+  }
+
+  /**
+   * Parses OpenAPI configuration from YAML content.
+   *
+   * @param yamlContent the YAML content to parse
+   * @return the parsed OpenAPI configuration
+   * @throws IOException if there's an error parsing the content
+   */
+  public static OpenAPI parseYaml(String yamlContent) throws IOException {
+    try {
+      return Yaml.mapper().readValue(yamlContent, OpenAPI.class);
+    } catch (Exception e) {
+      throw new IOException("Failed to parse YAML config: " + e.getMessage(), e);
+    }
+  }
+
+  /**
+   * Parses OpenAPI configuration from JSON content.
+   *
+   * @param jsonContent the JSON content to parse
+   * @return the parsed OpenAPI configuration
+   * @throws IOException if there's an error parsing the content
+   */
+  public static OpenAPI parseJson(String jsonContent) throws IOException {
+    try {
+      return Json.mapper().readValue(jsonContent, OpenAPI.class);
+    } catch (Exception e) {
+      throw new IOException("Failed to parse JSON config: " + e.getMessage(), e);
+    }
+  }
+}
diff --git a/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/schema/SchemaModelBuilder.java b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/schema/SchemaModelBuilder.java
new file mode 100644
index 00000000..52557a44
--- /dev/null
+++ b/vertx-grpc-protoc-plugin2/src/main/java/io/vertx/grpc/plugin/schema/SchemaModelBuilder.java
@@ -0,0 +1,619 @@
+package io.vertx.grpc.plugin.schema;
+
+import io.swagger.v3.oas.models.*;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.media.*;
+import io.swagger.v3.oas.models.parameters.RequestBody;
+import io.swagger.v3.oas.models.responses.ApiResponse;
+import io.swagger.v3.oas.models.responses.ApiResponses;
+import io.swagger.v3.oas.models.servers.Server;
+import io.vertx.grpc.plugin.descriptors.MessageDescriptor;
+import io.vertx.grpc.plugin.descriptors.MethodDescriptor;
+import io.vertx.grpc.plugin.descriptors.ServiceDescriptor;
+import io.vertx.grpc.plugin.descriptors.TranscodingDescriptor;
+
+import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Builds an OpenAPI model programmatically from gRPC service descriptors.
+ * <p>
+ * This class uses the Swagger Core library to construct an OpenAPI 3.0.0 specification from gRPC service definitions that have HTTP transcoding annotations.
+ */
+public class SchemaModelBuilder {
+
+  private static final String OPENAPI_VERSION = "3.0.0";
+  private static final String API_VERSION = "1.0.0";
+  private static final String DEFAULT_SERVER_URL = "http://localhost:8080";
+  private static final String APPLICATION_JSON = "application/json";
+
+  // Pattern to match path parameters with sub-paths like {name=projects/*/messages/*}
+  private static final Pattern SLASHED_PATH_PARAM_PATTERN = Pattern.compile("\\{([^}=]+)=([^}]+)}");
+
+  /**
+   * Builds an OpenAPI model from the given service descriptors.
+   *
+   * @param services the list of gRPC service descriptors
+   * @param packageName the package name to use in the API title
+   * @param messageDescriptors the map of message descriptors for schema generation
+   * @return the built OpenAPI model, or null if no services have transcoding methods
+   */
+  public static OpenAPI build(List<ServiceDescriptor> services, String packageName,
+    Map<String, MessageDescriptor> messageDescriptors) {
+    return build(services, packageName, messageDescriptors, null);
+  }
+
+  /**
+   * Builds an OpenAPI model from the given service descriptors, merging with a configuration.
+   *
+   * @param services the list of gRPC service descriptors
+   * @param packageName the package name to use in the API title
+   * @param messageDescriptors the map of message descriptors for schema generation
+   * @param config optional OpenAPI configuration to merge (info, servers, security, tags, etc.)
+   * @return the built OpenAPI model, or null if no services have transcoding methods
+   */
+  public static OpenAPI build(List<ServiceDescriptor> services, String packageName, Map<String, MessageDescriptor> messageDescriptors, OpenAPI config) {
+    List<ServiceDescriptor> transcodingServices = new ArrayList<>();
+
+    for (ServiceDescriptor service : services) {
+      if (!service.getTranscodingMethods().isEmpty()) {
+        transcodingServices.add(service);
+      }
+    }
+
+    if (transcodingServices.isEmpty()) {
+      return null;
+    }
+
+    OpenAPI openAPI = new OpenAPI();
+
+    openAPI.setOpenapi(OPENAPI_VERSION);
+    openAPI.setInfo(buildInfo(packageName));
+    openAPI.setServers(buildServers());
+    openAPI.setPaths(buildPaths(transcodingServices));
+    openAPI.setComponents(buildComponents(transcodingServices, messageDescriptors));
+
+    // Merge with config if provided
+    if (config != null) {
+      mergeConfig(openAPI, config);
+    }
+
+    return openAPI;
+  }
+
+  /**
+   * Merges configuration from a config OpenAPI into the generated OpenAPI. Config values override generated defaults for info, servers, security, tags, and externalDocs.
+   * Components are merged (securitySchemes from config are added to generated schemas).
+   */
+  private static void mergeConfig(OpenAPI target, OpenAPI config) {
+    // Override info if provided in config
+    if (config.getInfo() != null) {
+      target.setInfo(config.getInfo());
+    }
+
+    // Override servers if provided in config
+    if (config.getServers() != null && !config.getServers().isEmpty()) {
+      target.setServers(config.getServers());
+    }
+
+    // Set security if provided in config
+    if (config.getSecurity() != null && !config.getSecurity().isEmpty()) {
+      target.setSecurity(config.getSecurity());
+    }
+
+    // Set tags if provided in config
+    if (config.getTags() != null && !config.getTags().isEmpty()) {
+      target.setTags(config.getTags());
+    }
+
+    // Set externalDocs if provided in config
+    if (config.getExternalDocs() != null) {
+      target.setExternalDocs(config.getExternalDocs());
+    }
+
+    // Merge components (add securitySchemes from config, keep generated schemas)
+    if (config.getComponents() != null) {
+      Components targetComponents = target.getComponents();
+      if (targetComponents == null) {
+        targetComponents = new Components();
+        target.setComponents(targetComponents);
+      }
+
+      Components configComponents = config.getComponents();
+
+      // Add security schemes from config
+      if (configComponents.getSecuritySchemes() != null) {
+        if (targetComponents.getSecuritySchemes() == null) {
+          targetComponents.setSecuritySchemes(new LinkedHashMap<>());
+        }
+        targetComponents.getSecuritySchemes().putAll(configComponents.getSecuritySchemes());
+      }
+
+      // Add callbacks from config
+      if (configComponents.getCallbacks() != null) {
+        if (targetComponents.getCallbacks() == null) {
+          targetComponents.setCallbacks(new LinkedHashMap<>());
+        }
+        targetComponents.getCallbacks().putAll(configComponents.getCallbacks());
+      }
+
+      // Add examples from config
+      if (configComponents.getExamples() != null) {
+        if (targetComponents.getExamples() == null) {
+          targetComponents.setExamples(new LinkedHashMap<>());
+        }
+        targetComponents.getExamples().putAll(configComponents.getExamples());
+      }
+
+      // Add headers from config
+      if (configComponents.getHeaders() != null) {
+        if (targetComponents.getHeaders() == null) {
+          targetComponents.setHeaders(new LinkedHashMap<>());
+        }
+        targetComponents.getHeaders().putAll(configComponents.getHeaders());
+      }
+
+      // Add links from config
+      if (configComponents.getLinks() != null) {
+        if (targetComponents.getLinks() == null) {
+          targetComponents.setLinks(new LinkedHashMap<>());
+        }
+        targetComponents.getLinks().putAll(configComponents.getLinks());
+      }
+
+      // Add parameters from config
+      if (configComponents.getParameters() != null) {
+        if (targetComponents.getParameters() == null) {
+          targetComponents.setParameters(new LinkedHashMap<>());
+        }
+        targetComponents.getParameters().putAll(configComponents.getParameters());
+      }
+
+      // Add requestBodies from config
+      if (configComponents.getRequestBodies() != null) {
+        if (targetComponents.getRequestBodies() == null) {
+          targetComponents.setRequestBodies(new LinkedHashMap<>());
+        }
+        targetComponents.getRequestBodies().putAll(configComponents.getRequestBodies());
+      }
+
+      // Add responses from config
+      if (configComponents.getResponses() != null) {
+        if (targetComponents.getResponses() == null) {
+          targetComponents.setResponses(new LinkedHashMap<>());
+        }
+        targetComponents.getResponses().putAll(configComponents.getResponses());
+      }
+
+      // Merge schemas from config (config schemas override generated ones)
+      if (configComponents.getSchemas() != null) {
+        if (targetComponents.getSchemas() == null) {
+          targetComponents.setSchemas(new LinkedHashMap<>());
+        }
+        targetComponents.getSchemas().putAll(configComponents.getSchemas());
+      }
+    }
+
+    // Copy extensions from config
+    if (config.getExtensions() != null) {
+      for (Map.Entry<String, Object> entry : config.getExtensions().entrySet()) {
+        target.addExtension(entry.getKey(), entry.getValue());
+      }
+    }
+  }
+
+  private static Info buildInfo(String packageName) {
+    Info info = new Info();
+    info.setTitle(packageName + " gRPC API");
+    info.setVersion(API_VERSION);
+    info.setDescription("OpenAPI specification generated from gRPC service definitions with HTTP transcoding");
+    return info;
+  }
+
+  private static List<Server> buildServers() {
+    Server server = new Server();
+    server.setUrl(DEFAULT_SERVER_URL);
+    server.setDescription("gRPC server");
+    return Collections.singletonList(server);
+  }
+
+  private static Paths buildPaths(List<ServiceDescriptor> services) {
+    Paths paths = new Paths();
+
+    for (ServiceDescriptor service : services) {
+      for (MethodDescriptor method : service.getTranscodingMethods()) {
+        TranscodingDescriptor transcoding = method.getTranscoding();
+        if (transcoding != null) {
+          addPath(paths, service, method, transcoding, 0);
+
+          // Handle additional bindings
+          int bindingIndex = 1;
+          for (TranscodingDescriptor additionalBinding : transcoding.getAdditionalBindings()) {
+            addPath(paths, service, method, additionalBinding, bindingIndex++);
+          }
+        }
+      }
+    }
+
+    return paths;
+  }
+
+  private static void addPath(Paths paths, ServiceDescriptor service, MethodDescriptor method,
+    TranscodingDescriptor transcoding, int bindingIndex) {
+    String path = expandSlashedPathPatterns(transcoding.getPath());
+    String httpMethod = transcoding.getMethod().toLowerCase();
+
+    PathItem pathItem = paths.get(path);
+    if (pathItem == null) {
+      pathItem = new PathItem();
+      paths.addPathItem(path, pathItem);
+    }
+
+    Operation operation = buildOperation(service, method, transcoding, bindingIndex);
+
+    switch (httpMethod) {
+      case "get":
+        pathItem.setGet(operation);
+        break;
+      case "post":
+        pathItem.setPost(operation);
+        break;
+      case "put":
+        pathItem.setPut(operation);
+        break;
+      case "delete":
+        pathItem.setDelete(operation);
+        break;
+      case "patch":
+        pathItem.setPatch(operation);
+        break;
+      default:
+        pathItem.setPost(operation);
+    }
+  }
+
+  /**
+   * Expands slashed path parameters into standard OpenAPI path format. For example, paths with patterns like "name=projects/*" are expanded into standard OpenAPI path parameters
+   * like "projects/[project]".
+   *
+   * @param path the original path with slashed patterns
+   * @return the expanded path with standard OpenAPI parameters
+   */
+  private static String expandSlashedPathPatterns(String path) {
+    if (path == null || !path.contains("=")) {
+      return path;
+    }
+
+    Matcher matcher = SLASHED_PATH_PARAM_PATTERN.matcher(path);
+    StringBuilder result = new StringBuilder();
+
+    while (matcher.find()) {
+      String subPath = matcher.group(2); // e.g., "projects/*/messages/*" or "rooms/*/messages/*"
+      String expanded = expandSubPath(subPath);
+      matcher.appendReplacement(result, Matcher.quoteReplacement(expanded));
+    }
+    matcher.appendTail(result);
+
+    return result.toString();
+  }
+
+  /**
+   * Expands a sub-path pattern with wildcards into standard OpenAPI path parameters.
+   */
+  private static String expandSubPath(String subPath) {
+    String[] segments = subPath.split("/");
+    StringBuilder expanded = new StringBuilder();
+
+    for (int i = 0; i < segments.length; i++) {
+      if (i > 0) {
+        expanded.append("/");
+      }
+
+      String segment = segments[i];
+      if ("*".equals(segment) || "**".equals(segment)) {
+        // Find the previous segment to derive the parameter name
+        String paramName = deriveParamName(segments, i);
+        expanded.append("{").append(paramName).append("}");
+      } else {
+        expanded.append(segment);
+      }
+    }
+
+    return expanded.toString();
+  }
+
+  /**
+   * Derives a parameter name from the previous segment by trimming trailing "s".
+   */
+  private static String deriveParamName(String[] segments, int wildcardIndex) {
+    if (wildcardIndex > 0) {
+      String prevSegment = segments[wildcardIndex - 1];
+      if (prevSegment.endsWith("s")) {
+        return prevSegment.substring(0, prevSegment.length() - 1);
+      }
+      return prevSegment;
+    }
+    return "id" + wildcardIndex;
+  }
+
+  private static Operation buildOperation(ServiceDescriptor service, MethodDescriptor method,
+    TranscodingDescriptor transcoding, int bindingIndex) {
+    Operation operation = new Operation();
+    operation.setSummary(method.getName());
+
+    // Generate unique operationId: base name for index 0, append _httpMethod for additional bindings
+    String operationId = method.getVertxMethodName();
+    if (bindingIndex > 0) {
+      operationId = operationId + "_" + transcoding.getMethod().toLowerCase();
+    }
+    operation.setOperationId(operationId);
+    operation.setTags(Collections.singletonList(service.getName()));
+
+    if (method.getDocumentation() != null && !method.getDocumentation().isEmpty()) {
+      operation.setDescription(method.getDocumentation());
+    }
+
+    if (method.isDeprecated()) {
+      operation.setDeprecated(true);
+    }
+
+    // Add request body if needed
+    String body = transcoding.getBody();
+    if (body != null && !body.isEmpty()) {
+      operation.setRequestBody(buildRequestBody(method));
+    }
+
+    // Add responses
+    operation.setResponses(buildResponses(method));
+
+    return operation;
+  }
+
+  private static RequestBody buildRequestBody(MethodDescriptor method) {
+    RequestBody requestBody = new RequestBody();
+    requestBody.setRequired(true);
+
+    Content content = new Content();
+    MediaType mediaType = new MediaType();
+
+    Schema<?> schema = new Schema<>();
+    schema.set$ref("#/components/schemas/" + extractSimpleTypeName(method.getInputType()));
+    mediaType.setSchema(schema);
+
+    content.addMediaType(APPLICATION_JSON, mediaType);
+    requestBody.setContent(content);
+
+    return requestBody;
+  }
+
+  private static ApiResponses buildResponses(MethodDescriptor method) {
+    ApiResponses responses = new ApiResponses();
+
+    // Success response
+    ApiResponse successResponse = new ApiResponse();
+    successResponse.setDescription("Successful response");
+
+    Content successContent = new Content();
+    MediaType successMediaType = new MediaType();
+    Schema<?> successSchema = new Schema<>();
+    successSchema.set$ref("#/components/schemas/" + extractSimpleTypeName(method.getOutputType()));
+    successMediaType.setSchema(successSchema);
+    successContent.addMediaType(APPLICATION_JSON, successMediaType);
+    successResponse.setContent(successContent);
+    responses.addApiResponse("200", successResponse);
+
+    // Error response
+    ApiResponse errorResponse = new ApiResponse();
+    errorResponse.setDescription("Error response");
+
+    Content errorContent = new Content();
+    MediaType errorMediaType = new MediaType();
+    Schema<?> errorSchema = new Schema<>();
+    errorSchema.set$ref("#/components/schemas/GrpcError");
+    errorMediaType.setSchema(errorSchema);
+    errorContent.addMediaType(APPLICATION_JSON, errorMediaType);
+    errorResponse.setContent(errorContent);
+    responses.addApiResponse("default", errorResponse);
+
+    return responses;
+  }
+
+  private static Components buildComponents(List<ServiceDescriptor> services, Map<String, MessageDescriptor> descriptors) {
+    Components components = new Components();
+    Map<String, Schema> schemas = new LinkedHashMap<>();
+
+    // Collect all message types used
+    Set<String> types = collectAllTypes(services, descriptors);
+
+    // Generate schemas for all collected types
+    for (String type : types) {
+      Schema<?> schema = buildSchema(type, descriptors);
+      if (schema != null) {
+        String schemaName = extractSimpleTypeName(type);
+        schemas.put(schemaName, schema);
+      }
+    }
+
+    // Add GrpcError schema
+    schemas.put("GrpcError", buildGrpcErrorSchema());
+
+    components.setSchemas(schemas);
+    return components;
+  }
+
+  private static Set<String> collectAllTypes(List<ServiceDescriptor> services,
+    Map<String, MessageDescriptor> messageDescriptors) {
+    Set<String> allTypes = new LinkedHashSet<>();
+    Set<String> processedTypes = new HashSet<>();
+    Set<String> typesToProcess = new HashSet<>();
+
+    // Collect initial types from methods
+    for (ServiceDescriptor service : services) {
+      for (MethodDescriptor method : service.getTranscodingMethods()) {
+        typesToProcess.add(method.getInputType());
+        typesToProcess.add(method.getOutputType());
+      }
+    }
+
+    // Recursively collect nested message types
+    while (!typesToProcess.isEmpty()) {
+      String javaType = typesToProcess.iterator().next();
+      typesToProcess.remove(javaType);
+
+      if (processedTypes.contains(javaType)) {
+        continue;
+      }
+
+      processedTypes.add(javaType);
+      allTypes.add(javaType);
+
+      // Find nested message types
+      MessageDescriptor messageDesc = findMessageDescriptor(javaType, messageDescriptors);
+      if (messageDesc != null) {
+        for (MessageDescriptor.FieldDescriptor field : messageDesc.getFields()) {
+          if (field.getType().startsWith(".")) {
+            String nestedJavaType = field.getJavaType();
+            if (!processedTypes.contains(nestedJavaType)) {
+              typesToProcess.add(nestedJavaType);
+            }
+          }
+        }
+      }
+    }
+
+    return allTypes;
+  }
+
+  private static Schema<?> buildSchema(String javaType, Map<String, MessageDescriptor> messageDescriptors) {
+    MessageDescriptor messageDesc = findMessageDescriptor(javaType, messageDescriptors);
+    if (messageDesc == null) {
+      return null;
+    }
+
+    ObjectSchema schema = new ObjectSchema();
+    schema.setDescription("Protobuf message type: " + messageDesc.getFullName());
+
+    Map<String, Schema> properties = new LinkedHashMap<>();
+    for (MessageDescriptor.FieldDescriptor field : messageDesc.getFields()) {
+      Schema<?> fieldSchema = buildFieldSchema(field);
+      properties.put(field.getJsonName(), fieldSchema);
+    }
+    schema.setProperties(properties);
+
+    return schema;
+  }
+
+  private static Schema<?> buildFieldSchema(MessageDescriptor.FieldDescriptor field) {
+    Schema<?> baseSchema;
+
+    if (field.getType().startsWith(".")) {
+      // Reference to another message type
+      Schema<?> refSchema = new Schema<>();
+      refSchema.set$ref("#/components/schemas/" + extractSimpleTypeName(field.getJavaType()));
+      baseSchema = refSchema;
+    } else {
+      // Primitive type
+      baseSchema = mapToOpenApiSchema(field.getType());
+    }
+
+    if (field.isRepeated()) {
+      ArraySchema arraySchema = new ArraySchema();
+      arraySchema.setItems(baseSchema);
+      if (field.getDocumentation() != null && !field.getDocumentation().isEmpty()) {
+        arraySchema.setDescription(field.getDocumentation());
+      }
+      return arraySchema;
+    }
+
+    if (field.getDocumentation() != null && !field.getDocumentation().isEmpty()) {
+      baseSchema.setDescription(field.getDocumentation());
+    }
+
+    return baseSchema;
+  }
+
+  private static Schema<?> mapToOpenApiSchema(String protobufType) {
+    switch (protobufType) {
+      case "string":
+        return new StringSchema();
+      case "int32":
+      case "sint32":
+      case "sfixed32":
+        IntegerSchema int32Schema = new IntegerSchema();
+        int32Schema.setFormat("int32");
+        return int32Schema;
+      case "int64":
+      case "sint64":
+      case "sfixed64":
+        IntegerSchema int64Schema = new IntegerSchema();
+        int64Schema.setFormat("int64");
+        return int64Schema;
+      case "uint32":
+      case "fixed32":
+        IntegerSchema uint32Schema = new IntegerSchema();
+        uint32Schema.setFormat("int32");
+        return uint32Schema;
+      case "uint64":
+      case "fixed64":
+        // uint64 is represented as string in JSON to preserve precision
+        StringSchema uint64Schema = new StringSchema();
+        uint64Schema.setFormat("uint64");
+        return uint64Schema;
+      case "double":
+        NumberSchema doubleSchema = new NumberSchema();
+        doubleSchema.setFormat("double");
+        return doubleSchema;
+      case "float":
+        NumberSchema floatSchema = new NumberSchema();
+        floatSchema.setFormat("float");
+        return floatSchema;
+      case "bool":
+        return new BooleanSchema();
+      case "bytes":
+        StringSchema bytesSchema = new StringSchema();
+        bytesSchema.setFormat("byte");
+        return bytesSchema;
+      default:
+        return new StringSchema();
+    }
+  }
+
+  private static Schema<?> buildGrpcErrorSchema() {
+    ObjectSchema schema = new ObjectSchema();
+    Map<String, Schema> properties = new LinkedHashMap<>();
+
+    IntegerSchema codeSchema = new IntegerSchema();
+    codeSchema.setDescription("gRPC status code");
+    properties.put("code", codeSchema);
+
+    StringSchema messageSchema = new StringSchema();
+    messageSchema.setDescription("Error message");
+    properties.put("message", messageSchema);
+
+    ArraySchema detailsSchema = new ArraySchema();
+    detailsSchema.setItems(new ObjectSchema());
+    detailsSchema.setDescription("Additional error details");
+    properties.put("details", detailsSchema);
+
+    schema.setProperties(properties);
+    return schema;
+  }
+
+  private static MessageDescriptor findMessageDescriptor(String type, Map<String, MessageDescriptor> descriptors) {
+    for (MessageDescriptor desc : descriptors.values()) {
+      if (desc.getJavaType().equals(type)) {
+        return desc;
+      }
+    }
+    return null;
+  }
+
+  private static String extractSimpleTypeName(String name) {
+    if (name == null || name.isEmpty()) {
+      return name;
+    }
+    int lastDot = name.lastIndexOf('.');
+    return lastDot >= 0 ? name.substring(lastDot + 1) : name;
+  }
+}