{"id":32109191,"url":"https://github.com/redhat-appdev-practice/openapi-vertx-archetype","last_synced_at":"2026-02-21T17:02:19.324Z","repository":{"id":40425258,"uuid":"382392655","full_name":"redhat-appdev-practice/openapi-vertx-archetype","owner":"redhat-appdev-practice","description":"A Maven Archetype for bootstrapping an OpenAPI Contract-Driven application in Vert.x","archived":false,"fork":false,"pushed_at":"2022-05-09T13:17:57.000Z","size":328,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"trunk","last_synced_at":"2026-02-10T01:59:41.693Z","etag":null,"topics":["hacktoberfest","hacktoberfest2021"],"latest_commit_sha":null,"homepage":"","language":"Mustache","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhat-appdev-practice.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-02T15:46:04.000Z","updated_at":"2023-12-17T18:07:13.000Z","dependencies_parsed_at":"2022-08-09T20:10:17.097Z","dependency_job_id":null,"html_url":"https://github.com/redhat-appdev-practice/openapi-vertx-archetype","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/redhat-appdev-practice/openapi-vertx-archetype","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-appdev-practice%2Fopenapi-vertx-archetype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-appdev-practice%2Fopenapi-vertx-archetype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-appdev-practice%2Fopenapi-vertx-archetype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-appdev-practice%2Fopenapi-vertx-archetype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-appdev-practice","download_url":"https://codeload.github.com/redhat-appdev-practice/openapi-vertx-archetype/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-appdev-practice%2Fopenapi-vertx-archetype/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29387704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T22:07:52.078Z","status":"ssl_error","status_checked_at":"2026-02-12T22:07:49.026Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","hacktoberfest2021"],"created_at":"2025-10-20T12:57:29.600Z","updated_at":"2026-02-21T17:02:19.287Z","avatar_url":"https://github.com/redhat-appdev-practice.png","language":"Mustache","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI And Vert.x Bootstrap Archetype (Work In Progress)\n\nFollowing a [Contract-First API Development Approach](https://bit.ly/contract-first-api)\ncan be daunting depending on the tools, languages, and frameworks you might like to use.\nThis [Maven Archetype](https://maven.apache.org/guides/introduction/introduction-to-archetypes.html)\nis a quick-start for building a new OpenAPI driven application in [Eclipse Vert.x](https://vertx.io/).\n\n## Hacktoberfest Participants\n\nIf you would like to submit a pull against this repository and have it count toward Hacktoberfest, please be aware that this is what we are looking for:\n\n* Improvements to the archetype:\n  * Better or more idomatic workflow (Subjective and at the discretion of our team to decide if wanted)\n  * Fixes to spelling\n  * Updated or improved tooling\n\nIn order to avoid wasting your time and ours, it is recommended that you submit an issue describing your contribution first.\n\n**Thank you! And happy hacking!!**\n\n## Using This Archetype\n\n```bash\nmvn archetype:generate -DarchetypeGroupId=com.redhat.consulting \\\n                       -DarchetypeArtifactId=openapi-vertx-archetype \\\n                       -DarchetypeVersion=1.0.17 \\\n                       -Dpackage=com.redhat.runtimes \\\n                       -DgroupId=com.redhat.runtimes.vertx \\\n                       -DartifactId=openapi-vertx-todo \\\n                       -Dversion=0.0.1-SNAPSHOT \\\n                       -Dopenapi_app_database_library=jooq \\\n                       -Dopenapi_app_async_library=rxjava2 \\\n                       -Dopenapi_app_contract_uri=https://gist.githubusercontent.com/InfoSec812/a8e5ca3920e940ffcedced9990738f65/raw/0443d76f360f9722cf25ccf285f5270831203148/openapi-vertx-jooq.yml \\\n                       -Dinteractive=false\n```\n\n**NOTE:**\nYou can also override the default versions of many of the libraries using properties passed on the CLI. \n\nThe Archetype will create a maven multimodule project with a structure like this:\n\n```\n- Parent\n  |\n  +- models (POJOs for Hibernate/jOOQ ORMs)\n  |\n  +- data-access (optional jOOQ query DSL)\n  |\n  +- api (The Vert.x API stub where the business logic will be created)\n```\n\n### `models` Module: JPA Entities From OpenAPI Schemas\n\nThe models generated are from the **schemas** section of the OpenAPI Spec. The templates\nused allow you to include annotations which will work with JPA. For example:\n\nThis OpenAPI Schema . . . \n```yaml\ncomponents:\n  schemas:\n    title: Todo\n    description: 'A Todo list item'\n    type: object\n    x-java-class-annotations:\n      - '@javax.persistence.Entity'                 ## JPA Annotations\n      - '@javax.persistence.Table(name = \"todos\")'  ## JPA Annotations\n    properties:\n      title:\n        type: string\n      description:\n        type: string\n        x-java-field-annotations:\n          - '@javax.persistence.Column(columnDefinition = \"TEXT\")'\n      id:\n        type: string\n        format: uuid\n        x-java-field-annotations:\n          - '@javax.persistence.Id'\n          - '@javax.persistence.Column(name = \"id\", updatable = false, nullable = false)'\n          - '@javax.persistence.GeneratedValue(generator = \"UUID\")'\n          - '@org.hibernate.annotations.GenericGenerator(name = \"UUID\", strategy = \"org.hibernate.id.UUIDGenerator\")'\n          - '@javax.persistence.Column(name = \"id\", updatable = false, nullable = false)'\n      created:\n        type: string\n        format: datetime\n        x-java-field-annotations:\n          - '@javax.persistence.Column(name = \"created\", updatable = false, nullable = false)'\n          - '@org.hibernate.annotations.CreationTimestamp'\n      dueDate:\n        type: string\n        format: date\n    example:\n      title: My new todo\n      description: This is a really cool todo item\n      id: 81a9d97a-d42d-11eb-9edd-2bc577670ad3\n```\n\nWould be turned into this POJO:\n```java\n/**\n * A Todo list item\n */\n@ApiModel(description = \"A Todo list item\")\n@javax.annotation.Generated(value = \"org.openapitools.codegen.languages.SpringCodegen\", date = \"2020-08-03T08:22:24.280350-04:00[America/New_York]\")\n\n@javax.persistence.Entity\n@javax.persistence.Table(name = \"todos\")\npublic class Todo  implements Serializable {\n  private static final long serialVersionUID = 1L;\n\n  @JsonProperty(\"id\")\n  @javax.persistence.Id\n  @javax.persistence.GeneratedValue(generator = \"UUID\")\n  @org.hibernate.annotations.GenericGenerator(name = \"UUID\", strategy = \"org.hibernate.id.UUIDGenerator\")\n  @javax.persistence.Column(name = \"id\", updatable = false, nullable = false)\n  private UUID id;\n\n  @JsonProperty(\"title\")\n  private String title;\n\n  @JsonProperty(\"description\")\n  @javax.persistence.Column(columnDefinition = \"TEXT\")\n  private String description;\n\n  @JsonProperty(\"created\")\n  @org.hibernate.annotations.CreationTimestamp\n  @javax.persistence.Column(name = \"created\", updatable = false, nullable = false)\n  private OffsetDateTime created;\n\n  @JsonProperty(\"dueDate\")\n  private OffsetDateTime dueDate;\n\n  @JsonProperty(\"complete\")\n  private Boolean complete;\n\n  @JsonProperty(\"author\")\n  private String author;\n\n  public Todo id(UUID id) {\n    this.id = id;\n    return this;\n  }\n\n  // getters/setters/equals/hashcode methods \n\n}\n```\n\nThese are provided for using custom [Hibernate OpenAPI Generator Templates](https://github.com/redhat-appdev-practice/hibernate-openapi-templates)\n\nThe templates provide the following extension attributes:\n\n* `x-java-class-annotations`\n  * These need to be at the same level as the `title` for a schema object and are added above the class definition\n* `x-java-field-annotations`\n  * These need to be added inside of the individual fields of the schema and will be added to the private field definition\n* `x-java-getter-annotations`\n  * These need to be added inside of the individual fields of the schema and will be added to the getter methods\n\n### `data-access` Module: jOOQ Query DSL From JPA Entities\n\n[jOOQ](https://www.jooq.org/) allows you to write queries for relation databases in a generated Java query DSL. In order\nto create that DSL, it generally would analyze an existing database to formulate the DSL. That would require a DB-first\napproach and we are trying to create a contract-first approach. To support this, we instead generate the Hibernate\nmodels (Entities/POJOs) and use those models to generate a *fake* in-memory database and then jOOQ generates the DSL\nfrom there. The documentation for this process is [HERE](https://www.jooq.org/doc/latest/manual/code-generation/codegen-jpa/).\nSince this is complicated to set up, this Archetype does that setup for you using the POJOs generated from the `models`\nmodule. You, as a developer using this archetype, just need to ensure that your `schemas` objects in the OpenAPI\nspecification have the `x-java-class-annotations` and `x-java-field-annotations` added to create proper JPA entities and\nrelationships.\n\nWith the jOOQ query DSL created, you can use it in Vert.x via [Jans Klingsporn](https://github.com/jklingsporn) 's\nwonderful [implementation](https://github.com/jklingsporn/vertx-jooq) for Vert.x. See an example query below:\n\n```java\nClassicQueryExecutor queryExecutor = new JDBCClassicGenericQueryExecutor(configuration,vertx);\nFuture\u003cList\u003cTodo\u003e\u003e updatedCustom = queryExecutor.execute(dslContext -\u003e\n                dslContext\n                    .select()\n                    .from(Tables.TODO)\n                    .where(TODO.DUE_DATE.le(Date.now)))\n                    .fetch()\n                    .into(Todo.class);\n```\n\n### `api` Module: Vert.x Code Leveraging Hibernate Reactive or jOOQ\n\nThis is a work in progress and right now creates just a blank `MainVerticle` class\n\n## Options\n\n* `package`\n  * The Java package name to be used as the basis for code\n* `groupId`\n  * The Maven groupId for the generated project\n* `artifactId`\n  * The Maven artifactId for the generated project\n* `version`\n  * The Maven version for the generated project\n* `openapi_app_contract_uri`\n  * The Path or URL to an OpenAPI specification file in either YAML or JSON format\n  * Examples:\n    * https://petstore.swagger.io/v2/swagger.yaml\n    * https://petstore.swagger.io/v2/swagger.json\n    * /local/path/to/my/openapi.yml\n* `openapi_app_database_library`\n  * The Data Access library to be enabled\n    * `jooq` - [jOOQ](https://jooq.org)\n    * `hibernate` - [Hibernate Reactive](http://hibernate.org/reactive/)\n* `openapi_app_async_library`=\n  * The Async coordination API to enable\n    * `vertx` - Used the built-in composable coordination\n    * `rxjava2` - ReactiveX Streams  \n    * `mutiny` - The SmallRye Mutiny API\n\n## Current Status\n\n- Able to generate a maven multi-module project\n- Integrates OpenAPI Generator via Maven Plugin\n- Generates JPA Entity classes from the OpenAPI contract\n- Generates jOOQ Query DSL classes from the Hibernate/JPA entities\n- Creates a **stub** Vert.x Main Verticle\n- Allows you to choose between jOOQ and Hibernate Reactive\n- Allows you to choose between basic Vert.x style callbacks, RxJava2, and Mutiny for async APIs\n\n## Future Feature Ideas\n\n- Add JKube Maven Plugin as an option to simplify K8s/OpenShift deployment\n- Enable generating the Vert.x Web API Contract MainVerticle\n- Generate Auth code for OpenAPI/OpenID/WebAuthn/FIDO2/Auth0\n- Allow adding Tracing with OpenTracing\n- Allow choosing logging framework\n- Allow choosing metrics (Prometheus/Micrometer/etc...)\n- Add your idea to the GitHub issues!!!\n\n## FAQ\n\n- Why does it generate a Multi-module Maven project instead of a simple single Maven project?\n  - This is a limitation of the jOOQ JPA generator and I found that I liked it this way anyhow.\n- Can I update the version of **LIBRARY** without having to wait for a new version of this archetype?\n  - Yes, though you need to be careful doing so to ensure you don't put together incompatible versions. The following parameters are available as properties:\n    - `compiler_plugin_version`: Default value `3.8.1`\n    - `vertx_version`: Default value `4.1.2`\n    - `vertx_maven_plugin_version`: Default value `1.0.22`\n    - `mutiny_version`: Default value `2.12.0`\n    - `jkube_plugin_version`: Default value `1.3.0`\n    - `jooq_version`: Default value `3.15.2`\n    - `jooq_vertx_version`: Default value `6.3.0`\n    - `hibernate_reactive_version`: Default value `1.0.0.CR9`\n\n## Publishing To Maven Central\n\nThe build, testing, and publishing of this archetype is automated via GitHub\nActions using the Secrets defined on this repository. The user account is tied\nto [Deven Phillips](https://github.com/infosec812/)' and used to publish via\nthe [JBoss Nexus Staging Repository](https://developer.jboss.org/docs/DOC-52892).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-appdev-practice%2Fopenapi-vertx-archetype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-appdev-practice%2Fopenapi-vertx-archetype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-appdev-practice%2Fopenapi-vertx-archetype/lists"}