{"id":28187563,"url":"https://github.com/cchacin/microgen","last_synced_at":"2025-05-16T08:10:16.431Z","repository":{"id":34661523,"uuid":"144823441","full_name":"cchacin/MicroGen","owner":"cchacin","description":"An OpenAPI Spec Generator for Eclipse JakartaEE + Eclipse MicroProfile","archived":false,"fork":false,"pushed_at":"2023-03-15T13:58:17.000Z","size":4722,"stargazers_count":5,"open_issues_count":12,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-16T19:17:10.591Z","etag":null,"topics":["eclipse","eclipse-microprofile","jakartaee","javaee","javaee8","microprofile","openapi3"],"latest_commit_sha":null,"homepage":"https://microgen.io/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cchacin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-08-15T07:56:22.000Z","updated_at":"2023-06-22T11:58:48.000Z","dependencies_parsed_at":"2023-01-15T08:25:07.549Z","dependency_job_id":"9a532cbe-0ea0-4a02-89db-cbd26fcca919","html_url":"https://github.com/cchacin/MicroGen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cchacin%2FMicroGen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cchacin%2FMicroGen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cchacin%2FMicroGen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cchacin%2FMicroGen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cchacin","download_url":"https://codeload.github.com/cchacin/MicroGen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493368,"owners_count":22080127,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["eclipse","eclipse-microprofile","jakartaee","javaee","javaee8","microprofile","openapi3"],"created_at":"2025-05-16T08:10:10.755Z","updated_at":"2025-05-16T08:10:16.408Z","avatar_url":"https://github.com/cchacin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Eclipse MicroProfile logo](images/microprofile-logo.png)\n![Eclipse JakartaEE logo](images/jakartaee-logo.png)\n\n# MicroGen\n\n MicroGen is a tool to generate java code based on an [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) Spec file.\n\n## Features\n\n- Server API Contract (JAX-RS)\n- Request and Response java objects\n  - Inner static `Builder` class and utility methods\n- Enum value classes\n- `@BeanParams` for request parameters\n- Maven Archetype to quick start a JakartaEE + MicroProfile application\n- Dockerfile(s) with a JakartaEE + MicroProfile application server\n\n## User Guide\n\nGiven an OpenAPI Spec file:\n\n```yaml\nopenapi: 3.0.0\ninfo:\n  description: This is a sample server Petstore server.\n  version: 1.0.0\n  title: Swagger Petstore\ntags:\n  - name: pet\n    description: Everything about your Pets\npaths:\n  /pet:\n    post:\n      tags:\n        - pet\n      summary: Add a new pet to the store\n      description: ''\n      operationId: addPet\n      responses:\n        '405':\n          description: Invalid input\n      security:\n        - petstore_auth:\n            - 'write:pets'\n            - 'read:pets'\n      requestBody:\n        $ref: '#/components/requestBodies/Pet'\ncomponents:\n  requestBodies:\n    Pet:\n      content:\n        application/json:\n          schema:\n            $ref: '#/components/schemas/Pet'\n        application/xml:\n          schema:\n            $ref: '#/components/schemas/Pet'\n      description: Pet object that needs to be added to the store\n      required: true\n  schemas:\n    Pet:\n      type: object\n      required:\n        - name\n        - photoUrls\n      properties:\n        id:\n          type: integer\n          format: int64\n        category:\n          $ref: '#/components/schemas/Category'\n        name:\n          type: string\n          example: doggie\n        photoUrls:\n          type: array\n          items:\n            type: string\n        tags:\n          type: array\n          items:\n            $ref: '#/components/schemas/Tag'\n        status:\n          type: string\n          description: pet status in the store\n          enum:\n            - available\n            - pending\n            - sold\n```\n\nMicroGen will generate the following:\n\n#### Server API Contract (JAX-RS)\n\nJAX-RS interface with all the annotations necessary annotations\n\n```java\n@javax.annotation.Generated(value = \"org.openapitools.codegen.languages.MicroGen\")\npublic interface PetApi {\n  /**\n   * Add a new pet to the store\n   *\n   * @param pet Pet object that needs to be added to the store (required)\n   * @return {@code java.util.concurrent.CompletionStage\u003cjavax.ws.rs.core.Response\u003e}\n   */\n  @javax.ws.rs.POST\n  @javax.ws.rs.Path(\"pet\")\n  @javax.ws.rs.Consumes({\"application/json\", \"application/xml\"})\n  java.util.concurrent.CompletionStage\u003cjavax.ws.rs.core.Response\u003e addPet(\n          @javax.validation.constraints.NotNull @javax.validation.Valid Pet pet\n  ) throws javax.ws.rs.WebApplicationException;\n  .\n  .\n  .\n}\n```\n\n### `@BeanParams` for request parameters\n\n`@BeanParams` wrapper class to minimize the breaking changes in the Java API contract, this includes:\n  - `@PathParam`'s\n  - `@QueryParam`'s\n  - `@FormParam`'s\n  - `@HeaderParam`'s\n  - `@CookieParam`'s\n\nBut also the additional:\n\n  - `@Context UriInfo`\n  - `@Context HttpHeaders`\n\n```java\npublic class AddPetParams {\n    @javax.ws.rs.core.Context\n    public javax.ws.rs.core.HttpHeaders coreHttpHeaders;\n\n    public AddPetParams coreHttpHeaders(\n            final javax.ws.rs.core.HttpHeaders coreHttpHeaders\n    ) {\n        this.coreHttpHeaders = coreHttpHeaders;\n        return this;\n    }\n\n    @javax.ws.rs.core.Context\n    public javax.ws.rs.core.UriInfo coreUriInfo;\n\n    public AddPetParams coreUriInfo(\n            final javax.ws.rs.core.UriInfo coreUriInfo\n    ) {\n        this.coreUriInfo = coreUriInfo;\n        return this;\n    }\n}\n```\n\n### Request and Response objects:\n\nGenerate the Request and Response java objects with the `Json-b` annotations:\n  - `@JsonbProperty`\n  - `@JsonbCreator`\n  - `@JsonbPropertyOrder`\n  - `toString()`\n  - `equals`\n  - `hashCode`\n  - Inner static `Builder` class and utility methods\n\n  COMING SOON: Using immutables.org library\n\n  ```java\n  /**\n   * Pet\n   */\n  @javax.json.bind.annotation.JsonbPropertyOrder({\n    Pet.JSON_PROPERTY_ID,\n    Pet.JSON_PROPERTY_CATEGORY,\n    Pet.JSON_PROPERTY_NAME,\n    Pet.JSON_PROPERTY_PHOTO_URLS,\n    Pet.JSON_PROPERTY_TAGS,\n    Pet.JSON_PROPERTY_STATUS\n  })\n  @javax.annotation.Generated(value = \"org.openapitools.codegen.languages.MicroGen\")\n  @io.quarkus.runtime.annotations.RegisterForReflection\n  public final class Pet {\n      private final java.util.OptionalLong id;\n      public static final String JSON_PROPERTY_ID = \"id\";\n\n      @javax.validation.Valid\n      private final java.util.Optional\u003cCategory\u003e category;\n      public static final String JSON_PROPERTY_CATEGORY = \"category\";\n\n      @javax.validation.constraints.NotNull\n      private final String name;\n      public static final String JSON_PROPERTY_NAME = \"name\";\n\n      @javax.validation.constraints.NotNull\n      private final java.util.List\u003cString\u003e photoUrls;\n      public static final String JSON_PROPERTY_PHOTO_URLS = \"photoUrls\";\n\n      @javax.validation.Valid\n      private final java.util.Optional\u003cjava.util.List\u003cTag\u003e\u003e tags;\n      public static final String JSON_PROPERTY_TAGS = \"tags\";\n\n      private final StatusEnum status;\n      public static final String JSON_PROPERTY_STATUS = \"status\";\n\n      @javax.json.bind.annotation.JsonbCreator\n      public Pet(\n          @javax.json.bind.annotation.JsonbProperty(\"id\")\n          final java.util.OptionalLong id,\n          @javax.json.bind.annotation.JsonbProperty(\"category\")\n          final java.util.Optional\u003cCategory\u003e category,\n          @javax.json.bind.annotation.JsonbProperty(\"name\")\n          final String name,\n          @javax.json.bind.annotation.JsonbProperty(\"photoUrls\")\n          final java.util.List\u003cString\u003e photoUrls,\n          @javax.json.bind.annotation.JsonbProperty(\"tags\")\n          final java.util.Optional\u003cjava.util.List\u003cTag\u003e\u003e tags,\n          @javax.json.bind.annotation.JsonbProperty(\"status\")\n          final StatusEnum status\n    ) {\n        this.id = id;\n        this.category = category;\n        this.name = name;\n        this.photoUrls = photoUrls;\n        this.tags = tags;\n        this.status = status;\n    }\n\n    // getter omitted\n    // more details explained below\n  }\n  ```\n\n#### Inner static factory builder to make easier the instantiation:\n\n  ```java\n  public static Builder builder() {\n      return Builder.create();\n  }\n\n  public static final class Builder {\n      private java.util.OptionalLong                  id;\n      private java.util.Optional\u003cCategory\u003e            category;\n      private String                                  name;\n      private java.util.List\u003cString\u003e                  photoUrls;\n      private java.util.Optional\u003cjava.util.List\u003cTag\u003e\u003e tags;\n      private StatusEnum                              status;\n\n      private Builder() {\n      }\n\n      public static Builder create() {\n          return new Builder();\n      }\n\n      public Builder setId(final java.util.OptionalLong id) {\n          this.id = id;\n          return this;\n      }\n      // more info omitted\n    }\n  ```\n\n### Enum values\n\nGenerating all the enum values with the `@JsonbSerializer`'s and `@JsonbDeserializer`'s\n\n  ```java\n  @javax.json.bind.annotation.JsonbTypeSerializer(Pet.StatusEnumSerializer.class)\n  @javax.json.bind.annotation.JsonbTypeDeserializer(Pet.StatusEnumDeserializer.class)\n  public static enum StatusEnum {\n\n      AVAILABLE(\"available\"),\n      PENDING(\"pending\"),\n      SOLD(\"sold\");\n\n      private final String value;\n\n      StatusEnum(final String value) {\n          this.value = value;\n      }\n\n      public String getValue() {\n          return this.value;\n      }\n\n      @Override\n      public String toString() {\n          return String.valueOf(this.value);\n      }\n\n      @javax.json.bind.annotation.JsonbCreator\n      public static StatusEnum fromValue(final String text) {\n          return java.util.Arrays.stream(StatusEnum.values())\n                                 .filter(b -\u003e java.util.Objects.equals(String.valueOf(b.value), text))\n                                 .findFirst()\n                                 .orElse(null);\n      }\n  }\n  ```\n\n#### Enum's `Jsonb` Serializers/Deserializer\n\n  ```java\n  public static class StatusEnumSerializer implements javax.json.bind.serializer.JsonbSerializer\u003cStatusEnum\u003e {\n\n      public StatusEnumSerializer() { }\n\n      @Override\n      public void serialize(\n              StatusEnum aEnum,\n              javax.json.stream.JsonGenerator jsonGenerator,\n              javax.json.bind.serializer.SerializationContext serializationContext) {\n          jsonGenerator.write(aEnum.value);\n      }\n  }\n\n  public static class StatusEnumDeserializer implements javax.json.bind.serializer.JsonbDeserializer\u003cStatusEnum\u003e {\n\n      public StatusEnumDeserializer() {}\n\n      @Override\n      public StatusEnum deserialize(\n              javax.json.stream.JsonParser jsonParser,\n              javax.json.bind.serializer.DeserializationContext deserializationContext,\n              java.lang.reflect.Type type) {\n          return StatusEnum.fromValue(jsonParser.getString());\n      }\n  }\n  ```\n\n### Using MicroGen with the Maven Archetype\n\nExecute this command\n\n```bash\n$ mvn archetype:generate \\\n    -DgroupId=com.example \\\n    -DartifactId=example \\\n    -DarchetypeGroupId=io.microgen \\\n    -DarchetypeArtifactId=microgen-archetype\n```\n\nCheck what is created\n\n```bash\n$ cd example \u0026\u0026 tree . --dirsfirst\nexample\n├── src\n│   └── main\n│       ├── java\n│       │   └── com\n│       │       └── example\n│       │           └── JAXRSConfiguration.java\n│       ├── resources\n│       │   └── META-INF\n│       │       ├── microprofile-config.properties\n│       │       └── openapi.yml\n│       └── webapp\n│           └── WEB-INF\n│               └── beans.xml\n├── Dockerfile\n├── README.md\n├── mvnw\n├── mvnw.cmd\n└── pom.xml\n\n9 directories, 9 files\n```\n\nImplement the JAX-RS API contract\n\n```java\n@Path(\"v1\")\n@ApplicationScoped\npublic class PetResource implements PetApi {\n\n    @Override\n    public CompletionStage\u003cResponse\u003e addPet(Pet pet) throws WebApplicationException {\n        return CompletableFuture.completedFuture(\n                Response.noContent().build()\n        );\n    }\n\n    @Override\n    public CompletionStage\u003cResponse\u003e getPetById(GetPetByIdParams params) throws WebApplicationException {\n        return CompletableFuture.completedFuture(\n                Response.ok(\n                        Pet.builder()\n                           .setId(OptionalLong.of(1))\n                           .setName(\"pet\")\n                           .build()\n                ).build()\n        );\n    }\n```\n\nRun and enjoy\n\n```bash\n$ ./mvnw clean install\n```\n\n```bash\n$ docker rm -f example || true \u0026\u0026 docker run -d -p 9080:9080 --name example com.example/example:1.0-SNAPSHOT\n```\n\n```bash\n$ curl -s -X GET -H \"Accept: application/json\" http://localhost:9080/api/v1/pet/1 | jq .\n{\n  \"category\": {\n    \"id\": 1,\n    \"name\": \"\"\n  },\n  \"id\": 1,\n  \"name\": \"name\",\n  \"status\": \"available\"\n}\n```\n\n### Advance Features\n\n### Dependencies\n\n| Library              | Version | License |\n|:---------------------|:--------|:--------|\n| Eclipse JakartaEE    | 8.0.0   |         |\n| Eclipse MicroProfile | 3.0     |         |\n| OpenAPI Tools        | 4.1.1   |         |\n| Immutables           | 2.7.5   |         |\n\n[![forthebadge](https://forthebadge.com/images/badges/made-with-java.svg)](https://forthebadge.com) [![forthebadge](https://forthebadge.com/images/badges/built-with-love.svg)](https://forthebadge.com)\n\n[![forthebadge](https://forthebadge.com/images/badges/approved-by-george-costanza.svg)](https://forthebadge.com) [![forthebadge](https://forthebadge.com/images/badges/contains-technical-debt.svg)](https://forthebadge.com)\n\n![CodeQL](https://github.com/cchacin/MicroGen/workflows/Code%20scanning%20-%20action/badge.svg)\n![Java CI](https://github.com/cchacin/MicroGen/workflows/Java%20CI/badge.svg)\n![Greetings](https://github.com/cchacin/MicroGen/workflows/Greetings/badge.svg)\n![Release Drafter](https://github.com/cchacin/MicroGen/workflows/Release%20Management/badge.svg)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.microgen/microgen-parent/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.microgen/MicroGen)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=square)](http://makeapullrequest.com) [![Dependabot Status](https://api.dependabot.com/badges/status?host=github\u0026repo=cchacin/MicroGen)](https://dependabot.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcchacin%2Fmicrogen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcchacin%2Fmicrogen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcchacin%2Fmicrogen/lists"}