OpenAPI is a powerful tool for generating code from API specifications, but sometimes, default generators do not meet specific project needs. Let us delve into understanding the creation of a Java OpenAPI custom generator.<\/p>\n
The OpenAPI Specification<\/a> is a standardized format widely used for defining and documenting RESTful APIs, ensuring consistency and ease of use across different platforms and languages. To facilitate the development process, the OpenAPI Generator is a tool that enables developers to generate various assets directly from an API specification, such as client SDKs, server stubs, and documentation. By taking an OpenAPI Specification document as input, the OpenAPI Generator can automatically create these assets, significantly reducing development time and minimizing manual coding errors.<\/p>\n The OpenAPI Generator comes with a wide range of built-in generators that support multiple programming languages and frameworks. These built-in generators allow developers to quickly generate client libraries and server implementations in languages such as Java, Python, JavaScript, and more, helping them integrate APIs efficiently into their applications. Additionally, the OpenAPI Generator can produce comprehensive documentation in formats like HTML and Markdown, making it easier to share and understand API details.<\/p>\n Despite the versatility of these built-in generators, certain projects may have unique requirements that are not fully addressed by the default configurations. In such cases, developers can create a custom generator. A custom generator allows developers to define specific templates and settings that tailor the generated output to the particular needs of their project, such as adding custom file structures, and templates, or even modifying the default behavior of the generator. By extending or modifying the OpenAPI Generator, developers can produce assets that align more closely with their project\u2019s standards, ensuring compatibility and enhancing maintainability.<\/p>\n Creating a new OpenAPI Generator<\/a> provides significant advantages, particularly when standard generators don\u2019t fully meet the specific needs of a project. Custom generators allow developers to go beyond what is available out of the box and create API assets that are more closely aligned with project requirements.<\/p>\n Overall, building a custom OpenAPI generator allows teams to create optimized, standards-compliant, and feature-rich assets that integrate seamlessly with their project\u2019s ecosystem, making it a valuable approach for more complex or specialized API requirements.<\/p>\n Setting up a new generator project involves creating a Maven or Gradle project and configuring it to work with the OpenAPI Generator\u2019s codebase. Below is a step-by-step guide: Add the necessary dependencies to the OpenAPI generators extend from the The code defines a custom generator in Java, named This generator customizes the code generation process for OpenAPI specifications.<\/p>\n Mustache templates<\/a> define how the generated code will be structured. A basic Place this template in the templates folder within your project.<\/p>\n The template provided is used to generate Java classes based on an OpenAPI specification. This template is used within the OpenAPI Generator to create Java model classes dynamically by substituting the placeholders with values from the OpenAPI specification.<\/p>\n Unit testing is crucial for validating the logic within your generator. Using JUnit<\/a>, we can verify the correctness of the generator’s behavior.<\/p>\n The code defines a test class named Together, these test methods ensure that the Integration tests ensure that your custom generator works seamlessly with OpenAPI specifications. Below is a test setup that uses an example OpenAPI specification to generate code.<\/p>\n Run the test and verify that the generated output in Below is the Since this test checks that the output directory is created, the result will indicate whether code generation was successful. If the output directory exists and contains generated files, the assertion will pass; otherwise, it will fail.<\/p>\n Run the custom generator from the command line with:<\/p>\n This command applies your custom generator to the specified OpenAPI specification file.<\/p>\n Creating a custom OpenAPI generator allows you to fully control the structure and design of the generated code. With the ability to customize templates, add new configurations, and create tests, you can integrate the generator seamlessly into your development workflow. This approach helps meet specific project requirements and ensures that the generated code adheres to your team\u2019s coding standards.<\/p>\n","protected":false},"excerpt":{"rendered":" OpenAPI is a powerful tool for generating code from API specifications, but sometimes, default generators do not meet specific project needs. Let us delve into understanding the creation of a Java OpenAPI custom generator. 1. Introduction The OpenAPI Specification is a standardized format widely used for defining and documenting RESTful APIs, ensuring consistency and ease …<\/p>\n","protected":false},"author":26931,"featured_media":112,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[8],"tags":[1200,2034],"class_list":["post-127900","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-enterprise-java","tag-java","tag-openapi"],"yoast_head":"\n1.1 Why Create a New Generator?<\/h3>\n
\n
1.2 Benefits of OpenAPI Generator<\/h3>\n
\n
1.3 Use Cases for OpenAPI Generator<\/h3>\n
\n
<\/a>2. Creating an OpenAPI Generator Project<\/h2>\n
2.1 Add Dependencies<\/h3>\n
pom.xml<\/code> file:<\/p>\n<dependencies>\n <dependency>\n <groupId>org.openapitools<\/groupId>\n <artifactId>openapi-generator<\/artifactId>\n <version>your_jar_version<\/version>\n <\/dependency>\n<\/dependencies>\n<\/pre>\n
2.2 Implementing the Generator<\/h3>\n
2.2.1 Creating a Generator class<\/h4>\n
AbstractJavaCodegen<\/code> class or other base classes provided by the OpenAPI Generator library. Let’s understand the generator class below.<\/p>\npackage com.example.generator;\n\nimport org.openapitools.codegen.languages.AbstractJavaCodegen;\nimport org.openapitools.codegen.CodegenConfig;\n\npublic class MyCustomGenerator extends AbstractJavaCodegen implements CodegenConfig {\n\n public MyCustomGenerator() {\n super();\n outputFolder = \"generated-code\/my-custom-generator\";\n modelTemplateFiles.put(\"model.mustache\", \".java\");\n }\n\n @Override\n public String getName() {\n return \"my-custom-generator\";\n }\n\n @Override\n public void processOpts() {\n super.processOpts();\n apiTemplateFiles.put(\"api.mustache\", \".java\");\n supportingFiles.add(new SupportingFile(\"README.mustache\", \"\", \"README.md\"));\n }\n}\n<\/pre>\n2.2.1.1 Code explanation<\/h5>\n
MyCustomGenerator<\/code>, which extends the AbstractJavaCodegen<\/code> class and implements the CodegenConfig<\/code> interface from the OpenAPI tools library.<\/p>\n\n
MyCustomGenerator()<\/code>, the superclass’s constructor is called with super()<\/code>. The outputFolder<\/code> is set to \"generated-code\/my-custom-generator\"<\/code>, which specifies the directory where the generated files will be stored.<\/li>\n\"model.mustache\"<\/code> files to generate .java<\/code> files.<\/li>\ngetName()<\/code> method returns the name of the generator, \"my-custom-generator\"<\/code>. This is used by OpenAPI tools to recognize the generator.<\/li>\nprocessOpts()<\/code> method, which handles additional processing options, is overridden. It first calls the superclass\u2019s method, then maps \"api.mustache\"<\/code> templates to .java<\/code> files and adds a supporting file, README.md<\/code>, generated from the \"README.mustache\"<\/code> template.<\/li>\n<\/ul>\n2.2.2 Creating a Mustache template<\/h4>\n
model.mustache<\/code> template look like this:<\/p>\npackage {{package}};\n\npublic class {{classname}} {\n {{#vars}}\n private {{datatype}} {{name}};\n {{\/vars}}\n}\n<\/pre>\n2.2.2.1 Code explanation<\/h5>\n
\n
\n
\n
User<\/code>, {{classname}}<\/code> will be replaced with User<\/code>.<\/li>\n<\/ul>\n<\/li>\n\n
{{#vars}}<\/code> starts a loop over a list of properties (or variables) within the class, and {{\/vars}}<\/code> ends this loop.<\/li>\nvars<\/code> item represents an attribute (e.g., a field of a model) defined in the OpenAPI spec, such as id<\/code>, name<\/code>, or email<\/code> in a User<\/code> class.<\/li>\n<\/ul>\n<\/li>\n\n
String<\/code>, int<\/code>, or boolean<\/code>, based on the OpenAPI specification\u2019s type definitions.<\/li>\nname<\/code> is defined as a string type, {{datatype}}<\/code> will be replaced with String<\/code>.<\/li>\n<\/ul>\n<\/li>\n\n
User<\/code> model, the name<\/code> attribute will be used to generate private String name;<\/code>.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/a>3. Unit Testing<\/h2>\n
package com.example.generator;\n\nimport org.junit.jupiter.api.Test;\nimport org.openapitools.codegen.SupportingFile;\n\nimport static org.junit.jupiter.api.Assertions.*;\n\npublic class MyCustomGeneratorTest {\n\n @Test\n public void testGeneratorName() {\n MyCustomGenerator generator = new MyCustomGenerator();\n assertEquals(\"my-custom-generator\", generator.getName());\n }\n\n @Test\n public void testOutputFolder() {\n MyCustomGenerator generator = new MyCustomGenerator();\n assertTrue(generator.outputFolder.contains(\"my-custom-generator\"));\n }\n\n @Test\n public void testProcessOpts() {\n MyCustomGenerator generator = new MyCustomGenerator();\n generator.processOpts();\n\n \/\/ Check that the model template file is set correctly\n assertTrue(generator.modelTemplateFiles.containsKey(\"model.mustache\"));\n assertEquals(\".java\", generator.modelTemplateFiles.get(\"model.mustache\"));\n\n \/\/ Check that the api template file is set correctly\n assertTrue(generator.apiTemplateFiles.containsKey(\"api.mustache\"));\n assertEquals(\".java\", generator.apiTemplateFiles.get(\"api.mustache\"));\n\n \/\/ Check that supporting files contain README.md\n assertTrue(generator.supportingFiles.stream().anyMatch(\n file -> file.destinationFilename.equals(\"README.md\")\n ));\n }\n}\n<\/pre>\nMyCustomGeneratorTest<\/code>, which tests the behavior of the MyCustomGenerator<\/code> class. It is part of the com.example.generator<\/code> package and uses the JUnit 5 testing framework, imported with org.junit.jupiter.api.Test<\/code> and org.junit.jupiter.api.Assertions.*<\/code>, to validate specific aspects of the MyCustomGenerator<\/code> implementation.<\/p>\n\n
testGeneratorName<\/code> method creates an instance of MyCustomGenerator<\/code> and verifies that the generator\u2019s name is set correctly. The method calls generator.getName()<\/code> and uses assertEquals<\/code> to confirm that it returns \"my-custom-generator\"<\/code>, as expected.<\/li>\ntestOutputFolder<\/code> method also creates an instance of MyCustomGenerator<\/code> and checks if the outputFolder<\/code> variable contains the expected value, \"my-custom-generator\"<\/code>. It uses assertTrue<\/code> to validate that the outputFolder<\/code> path includes this string, confirming that the output folder is configured correctly.<\/li>\ntestProcessOpts<\/code>: This new test case verifies the configurations that processOpts sets up:\n\n
MyCustomGenerator<\/code> class has the correct name and output folder settings, providing basic verification for key configurations of the generator. Running these tests will result in an output indicating whether each assertion passes or fails.<\/p>\n[INFO] Running MyCustomGeneratorTest\n[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.123 s\n[INFO] All tests passed.\n<\/pre>\n
<\/a>4. Integration Test<\/h2>\n
package com.example.generator;\n\nimport org.junit.jupiter.api.Test;\nimport org.openapitools.codegen.ClientOptInput;\nimport org.openapitools.codegen.DefaultGenerator;\nimport org.openapitools.codegen.config.CodegenConfigurator;\n\nimport static org.junit.jupiter.api.Assertions.assertTrue;\nimport java.io.File;\n\npublic class MyCustomGeneratorIntegrationTest {\n\n @Test\n public void testGenerateCodeFromSpec() {\n \/\/ \"example.yaml\" is an OpenAPI specification file located in src\/test\/resources.\n \/\/ It defines the API endpoints, data models, and responses according to the OpenAPI standard.\n \/\/ This file provides the blueprint for generating the API client\/server code with the custom generator.\n CodegenConfigurator configurator = new CodegenConfigurator()\n .setGeneratorName(\"my-custom-generator\")\n .setInputSpec(\"src\/test\/resources\/example.yaml\")\n .setOutputDir(\"out\/my-custom-generator\");\n\n \/\/ Converts configuration into the input format for code generation\n ClientOptInput input = configurator.toClientOptInput();\n DefaultGenerator generator = new DefaultGenerator();\n\n \/\/ Runs the generator with the provided specification, generating code in the output directory\n generator.opts(input).generate();\n\n \/\/ Verification: Check if output directory contains generated files\n File outputDir = new File(\"out\/my-custom-generator\");\n assertTrue(outputDir.exists() && outputDir.isDirectory(), \"Output directory should exist and contain generated files.\");\n }\n}\n<\/pre>\nout\/my-custom-generator<\/code> matches your custom template\u2019s specifications. Make note that the example.yaml<\/code> file will depend on your business requirements.<\/p>\nexample.yaml<\/code> file used for this article:<\/p>\nopenapi: 3.0.0\ninfo:\n title: Sample API\n version: 1.0.0\n description: A simple API for demonstrating OpenAPI code generation with custom settings.\n\npaths:\n \/items:\n get:\n summary: Retrieve a list of items\n operationId: getItems\n responses:\n '200':\n description: A list of items.\n content:\n application\/json:\n schema:\n type: array\n items:\n $ref: '#\/components\/schemas\/Item'\n post:\n summary: Create a new item\n operationId: createItem\n requestBody:\n description: Details of the item to create\n required: true\n content:\n application\/json:\n schema:\n $ref: '#\/components\/schemas\/Item'\n responses:\n '201':\n description: Item created successfully.\n '400':\n description: Invalid input.\n\n \/items\/{itemId}:\n get:\n summary: Get details of a specific item\n operationId: getItemById\n parameters:\n - name: itemId\n in: path\n required: true\n schema:\n type: integer\n example: 1\n responses:\n '200':\n description: Details of the specified item.\n content:\n application\/json:\n schema:\n $ref: '#\/components\/schemas\/Item'\n '404':\n description: Item not found.\n\ncomponents:\n schemas:\n Item:\n type: object\n required:\n - id\n - name\n properties:\n id:\n type: integer\n example: 1\n name:\n type: string\n example: \"Sample Item\"\n description:\n type: string\n example: \"This is a sample item.\"\n price:\n type: number\n format: float\n example: 19.99\n<\/pre>\n<\/a>5. Using the Custom Generator<\/h2>\n
java -jar openapi-generator-cli.jar generate \\\n -g my-custom-generator \\\n -i \/path\/to\/openapi.yaml \\\n -o \/path\/to\/output\n<\/pre>\n
<\/a>6. Conclusion<\/h2>\n