forked from loafle/openapi-generator-original
61 lines
75 KiB
HTML
61 lines
75 KiB
HTML
<!doctype html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width">
|
|
<meta name="generator" content="Docusaurus">
|
|
<link rel="preconnect" href="https://www.google-analytics.com">
|
|
<script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","UA-132927057-1","auto"),ga("send","pageview")</script>
|
|
<script async src="https://www.google-analytics.com/analytics.js"></script>
|
|
<link rel="preconnect" href="https://www.google-analytics.com">
|
|
<script>window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)},ga.l=+new Date,ga("create","UA-132927057-1","auto"),ga("send","pageview")</script>
|
|
<script async src="https://www.google-analytics.com/analytics.js"></script>
|
|
<script src="https://buttons.github.io/buttons.js"></script>
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.0/clipboard.min.js"></script>
|
|
<script src="/js/code-block-buttons.js"></script>
|
|
|
|
<title data-react-helmet="true">Customization</title>
|
|
|
|
<meta data-react-helmet="true" http-equiv="x-ua-compatible" content="ie=edge"><meta data-react-helmet="true" property="og:title" content="OpenAPI Generator · Generate clients, servers, and documentation from OpenAPI 2.0/3.x documents"><meta data-react-helmet="true" property="og:image" content="https://openapi-generator.tech/img/docusaurus.png"><meta data-react-helmet="true" property="twitter:image" content="https://openapi-generator.tech/img/docusaurus.png"><meta data-react-helmet="true" name="twitter:image:alt" content="Image for OpenAPI Generator · Generate clients, servers, and documentation from OpenAPI 2.0/3.x documents"><meta data-react-helmet="true" name="twitter:card" content="summary"><meta data-react-helmet="true" name="description" content="## User-defined Templates"><meta data-react-helmet="true" property="og:description" content="## User-defined Templates"><meta data-react-helmet="true" property="og:url" content="https://openapi-generator.tech/docs/customization">
|
|
|
|
<link data-react-helmet="true" rel="shortcut icon" href="/img/favicon.png">
|
|
|
|
|
|
<link rel="stylesheet" href="/styles.ec5417b5.css">
|
|
|
|
</head>
|
|
<body>
|
|
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}function e(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}var n=window.matchMedia("(prefers-color-scheme: dark)");n.addListener((function(n){null===e()&&t(n.matches?"dark":"")}));var a=e();null!==a?t(a):n.matches&&t("dark")}()</script>
|
|
<div id="__docusaurus">
|
|
<nav class="navbar navbar--light navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><div aria-label="Navigation bar toggle" class="navbar__toggle" role="button" tabindex="0"><svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 30 30" role="img" focusable="false"><title>Menu</title><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></div><a aria-current="page" class="navbar__brand active" href="/"><img class="navbar__logo" src="/img/mono-logo.svg" alt="OpenAPI Tools logo"><strong>OpenAPI Generator</strong></a><a class="navbar__item navbar__link" href="/docs/installation">Getting Started</a><a class="navbar__item navbar__link" href="/docs/generators">Generators</a><a class="navbar__item navbar__link" href="/docs/roadmap">Roadmap</a><a class="navbar__item navbar__link" href="/docs/faq">FAQ</a><a class="navbar__item navbar__link" href="/team">Team</a><a class="navbar__item navbar__link" href="/blog">Blog</a><a class="navbar__item navbar__link" activeclassname="navbar__link--active" to="https://api.openapi-generator.tech" href="https://api.openapi-generator.tech">API</a></div><div class="navbar__items navbar__items--right"><div class="react-toggle react-toggle--disabled displayOnlyInLargeViewport_1gtM"><div class="react-toggle-track"><div class="react-toggle-track-check"><span class="toggle_keGJ moon_1gwN"></span></div><div class="react-toggle-track-x"><span class="toggle_keGJ sun_3CPA"></span></div></div><div class="react-toggle-thumb"></div><input type="checkbox" disabled="" aria-label="Dark mode toggle" class="react-toggle-screenreader-only"></div><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input type="search" id="search_input_react" placeholder="Search" aria-label="Search" class="navbar__search-input search-bar"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div><div class="navbar-sidebar"><div class="navbar-sidebar__brand"><a aria-current="page" class="navbar__brand active" href="/"><img class="navbar__logo" src="/img/mono-logo.svg" alt="OpenAPI Tools logo"><strong>OpenAPI Generator</strong></a></div><div class="navbar-sidebar__items"><div class="menu"><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/installation">Getting Started</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/generators">Generators</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/roadmap">Roadmap</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/faq">FAQ</a></li><li class="menu__list-item"><a class="menu__link" href="/team">Team</a></li><li class="menu__list-item"><a class="menu__link" href="/blog">Blog</a></li><li class="menu__list-item"><a class="menu__link" activeclassname="navbar__link--active" to="https://api.openapi-generator.tech" href="https://api.openapi-generator.tech">API</a></li></ul></div></div></div></nav><div class="main-wrapper"><div class="docPage_1kjD"><div class="docSidebarContainer_1cYp"><div class="sidebar_1kLs"><div class="menu menu--responsive"><button aria-label="Open Menu" class="button button--secondary button--sm menu__button" type="button"><svg class="sidebarMenuIcon_2vk4" xmlns="http://www.w3.org/2000/svg" height="24" width="24" viewBox="0 0 32 32" role="img" focusable="false"><title>Menu</title><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><ul class="menu__list"><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Getting Started</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/installation">CLI Installation</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/plugins">Plugins</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/online">Online</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/usage">Usage</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/globals">Global Properties</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/configuration">Configuration Options</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/file-post-processing">File post-processing</a></li></ul></li><li class="menu__list-item"><a class="menu__link menu__link--sublist menu__link--active" href="#!">Extending</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/templating">Using Templates</a></li><li class="menu__list-item"><a aria-current="page" class="menu__link menu__link--active" href="/docs/customization">Customization</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/debugging">Debugging</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/integrations">Workflow Integrations</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Contributing</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/contributing">Guidelines</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/code-of-conduct">Code of Conduct</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/contribute-building">Building the code</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/new-generator">Create a New Generator</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">About</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/roadmap">Roadmap</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/swagger-codegen-migration">Migrating from Swagger Codegen</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/fork-qna">Swagger Codegen Fork: Q&A</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Releases</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/release-summary">Release Summary</a></li><li class="menu__list-item"><a class="menu__link" href="/docs/release-3-0-0">Release Notes: 3.0.0</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">API</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" href="/docs/generators">Generators List</a></li></ul></li></ul></div></div></div><main class="docMainContainer_FFX1"><div class="padding-vert--lg"><div class="container"><div class="row"><div class="col"><div class="docItemContainer_2cwg"><article><header><h1 class="docTitle_1vWb">Customization</h1></header><div class="markdown"><h2><a aria-hidden="true" tabindex="-1" class="anchor" id="user-defined-templates"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#user-defined-templates" title="Direct link to heading">#</a>User-defined Templates</h2><p>The most common scenario for user customization is to override the built-in templates with small modifications. That scenario's documentation is in our <a href="/docs/templating">templating</a> page, and differs from user-defined templates.</p><p>Prior to release 5.0.0, whenever a user wanted to include templates which weren't built-in or weren't known to the generator at compile time, they'd need to follow the more involved approach of creating a custom generator as documented later in this document. Beginning in 5.0.0, a user may now provide additional supporting files and extensions to built-in templates via configuration. This feature requires using the external configuration file feature.</p><p>Consider that you might want to add some static documentation such as <code>AUTHORS.md</code> and a custom tooling script. Rather than a single file for API definitions you also want an implementation file and a separate interface file for each.</p><p>You might have an external configuration file named <code>config.yaml</code> which defines additional properties like this for a <code>kotlin</code> client generator:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-yaml codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token key atrule">additionalProperties</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">artifactId</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> kotlin</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">petstore</span><span class="token punctuation" style="color:rgb(248, 248, 242)">-</span><span class="token plain">client</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">serializableModel</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"true"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token key atrule">dateLibrary</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> java8</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>You would generate via CLI with the command:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-shell codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">openapi-generator generate -g kotlin -i spec.yaml -o outdir -c config.yaml</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>To support the above scenario with custom templates, ensure that you're pointing to your custom template directory and add a <code>files</code> node with template file definitions to your config:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">templateDir: my_custom_templates</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">additionalProperties:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> artifactId: kotlin-petstore-client</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> serializableModel: </span><span class="token string" style="color:rgb(255, 121, 198)">"true"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> dateLibrary: java8</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">files:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> AUTHORS.md: </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> api_interfaces.mustache:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> templateType: API</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> destinationFilename: Interface.kt</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> api.mustache:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> templateType: API</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> destinationFilename: Impl.kt</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> other/check.mustache:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> folder: scripts</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> destinationFilename: check.sh</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> templateType: SupportingFiles</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>The keys under the <code>files</code> node are your template filenames. These honor the same resolution order as all other templates.</p><p>The above configuration will do the following:</p><ul><li>Copy <code>my_custom_templates/AUTHORS.md</code> to the generated output directory without processing via the template engine (due to template file extension). The empty object definition following <code>AUTHORS.md</code> allows the tool to infer the target output filename in the root of the output directory.</li><li>Compile a user-provided <code>my_custom_templates/api_interfaces.mustache</code> following our usual API template compilation logic. That is, one file will be created per API; APIs are generated defined according to tags in your spec documentation. The destination filename of <code>Interface.kt</code> will act as a suffix for the filename. So, a tag of <code>Equipment</code> will output a corresponding <code>EquipmentInterface.kt</code>.</li><li>Because <code>api.mustache</code> is the same mustache filename as used in your target generator (<code>kotlin</code> in this example), we support the following:<ul><li>The destination filename provides a suffix for the generated output. APIs generate per tag in your specification. So, a tag of <code>Equipment</code> will output a corresponding <code>EquipmentImpl.kt</code>. This option will be used whether <code>api.mustache</code> targets a user customized template or a built-in template.</li><li>The built-in template will be used if you haven't provided an customized template. The kotlin generator defines the suffix as simply <code>.kt</code>, so this scenario would modify only the generated file suffixes according to the previous bullet point.</li><li>Your <code>api.mustache</code> will be used if it exists in your custom template directory. For generators with library options, such as <code>jvm-okhttp3</code> in the kotlin generator, your file must exist in the same relative location as the embedded template. For kotlin using the <code>jvm-okhttp3</code> library option, this file would need to be located at <code>my_custom_templates/libraries/jvm-okhttp/api.mustache</code>. See <a href="/docs/templating">templating</a> for more details.</li></ul></li><li>Compile <code>my_custom_templates/other/check.mustache</code> with the supporting files bundle, and output to <code>scripts/check.sh</code> in your output directory. Note that we don't currently support setting file flags on output, so scripts such as these will either have to be sourced rather than executed, or have file flags set separately after generation (external to our tooling).</li></ul><p>The <code>templateType</code> option will default to <code>SupportingFiles</code>, so the option for <code>other/check.mustache</code> is redundant and provided to demonstrate the full template file configuration options. The available template types are:</p><ul><li>API</li><li>APIDocs</li><li>APITests</li><li>Model</li><li>ModelDocs</li><li>ModelTests</li><li>SupportingFiles</li></ul><p>Excluding <code>SupportingFiles</code>, each of the above options may result in multiple files. API related types create a file per API. Model related types create a file for each model.</p><p>Note that user-defined templates will merge with built-in template definitions. If a supporting file with the sample template file path exists, it will be replaced with the user-defined template, otherwise the user-defined template will be added to the list of template files to compile. If the generator's built-in template is <code>model_docs.mustache</code> and you define <code>model-docs.mustache</code>, this will result in duplicated model docs (if <code>destinationFilename</code> differs) or undefined behavior as whichever template compiles last will overwrite the previous model docs (if <code>destinationFilename</code> matches the extension or suffix in the generator's code).</p><h2><a aria-hidden="true" tabindex="-1" class="anchor" id="custom-generator-and-template"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#custom-generator-and-template" title="Direct link to heading">#</a>Custom Generator (and Template)</h2><a id="creating-a-new-template"></a> If none of the built-in generators suit your needs and you need to do more than just modify the mustache templates to tweak generated code, you can create a brand new generator and its associated templates. OpenAPI Generator can help with this, using the `meta` command:<pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar meta \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -o out/generators/my-codegen -n my-codegen -p com.my.company.codegen</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>This will create a new directory <code>out/generators/my-codegen</code>, with all the files you need to get started - including a <code>README.md</code>. Once modified and compiled, you can use your new codegen just like any other, with your own custom-rolled logic.</p><p>These names can be anything you like. If you are building a client for the whitespace language, maybe you'd use the options <code>-o out/generators/whitespace -n whitespace</code>. They can be the same, or different, it doesn't matter. The <code>-n</code> value will be become the template name.</p><p><strong>NOTE</strong> Convention is to use kebab casing for names passed to <code>-n</code>. Example, <code>scala-finatra</code> would become <code>ScalaFinatraGenerator</code>.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor" id="use-your-new-generator-with-the-cli"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#use-your-new-generator-with-the-cli" title="Direct link to heading">#</a>Use your new generator with the CLI</h3><p>To compile your library, enter the <code>out/generators/my-codegen</code> directory, run <code>mvn package</code>.</p><p><strong>NOTE</strong> Running your custom generator requires adding it to the classpath. This differs on <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html">Windows</a> slightly from <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/unix/classpath.html">unix</a>.
|
|
If you are running a Windows Subsystem for Linux or a shell such as gitbash, and have issues with the unix variant, try the Windows syntax below.</p><p>Now, execute the generator:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -cp out/generators/my-codegen/target/my-codegen-openapi-generator-1.0.0.jar:modules/openapi-generator-cli/target/openapi-generator-cli.jar org.openapitools.codegen.OpenAPIGenerator</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>For Windows users, you will need to use <code>;</code> instead of <code>:</code> in the classpath, e.g.</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -cp </span><span class="token string" style="color:rgb(255, 121, 198)">"out/generators/my-codegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar"</span><span class="token plain"> org.openapitools.codegen.OpenAPIGenerator</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Note the <code>my-codegen</code> is an option for <code>-g</code> now, and you can use the usual arguments for generating your code:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -cp out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.jar:modules/openapi-generator-cli/target/openapi-generator-cli.jar \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> org.openapitools.codegen.OpenAPIGenerator generate -g my-codegen \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -o ./out/myClient</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>For Windows users:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -cp </span><span class="token string" style="color:rgb(255, 121, 198)">"out/codegens/customCodegen/target/my-codegen-openapi-generator-1.0.0.jar;modules/openapi-generator-cli/target/openapi-generator-cli.jar"</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">\</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> org.openapitools.codegen.OpenAPIGenerator generate -g my-codegen </span><span class="token punctuation" style="color:rgb(248, 248, 242)">\</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml </span><span class="token punctuation" style="color:rgb(248, 248, 242)">\</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -o ./out/myClient</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><h3><a aria-hidden="true" tabindex="-1" class="anchor" id="use-your-new-generator-with-the-maven-plugin"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#use-your-new-generator-with-the-maven-plugin" title="Direct link to heading">#</a>Use your new generator with the maven plugin</h3><p>Install your library to your local maven repository by running:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">mvn clean </span><span class="token function" style="color:rgb(80, 250, 123)">install</span><span class="token plain"> -f out/generators/my-codegen</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>This will install <code>org.openapitools:my-codegen-openapi-generator:1.0.0</code> to your local maven repository.</p><p>You can use this as additional dependency of the <code>openapi-generator-maven-plugin</code> plugin and use <code>my-codegen</code> as <code>generatorName</code> value:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-xml codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">plugin</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">groupId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">org.openapitools</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">groupId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">artifactId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">openapi-generator-maven-plugin</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">artifactId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">version</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">${openapi-generator-version}</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">version</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">executions</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">execution</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">id</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">generate-client-code</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">id</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">goals</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">goal</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">generate</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">goal</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">goals</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">configuration</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">generatorName</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">my-codegen</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">generatorName</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token comment" style="color:rgb(98, 114, 164)"><!-- other configuration ... --></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">configuration</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">execution</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">executions</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">dependencies</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">dependency</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">groupId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">org.openapitools</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">groupId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">artifactId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">my-codegen-openapi-generator</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">artifactId</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"><</span><span class="token tag" style="color:rgb(255, 121, 198)">version</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain">1.0.0</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">version</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">dependency</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">dependencies</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token tag punctuation" style="color:rgb(248, 248, 242)"></</span><span class="token tag" style="color:rgb(255, 121, 198)">plugin</span><span class="token tag punctuation" style="color:rgb(248, 248, 242)">></span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>If you publish your artifact to a distant maven repository, do not forget to add this repository as <code>pluginRepository</code> for your project.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor" id="selective-generation"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#selective-generation" title="Direct link to heading">#</a>Selective generation</h2><p>You may not want to generate <em>all</em> models in your project. Likewise, you may want just one or two apis to be written. If that's the case, you can use system properties or <a href="/docs/globals">global properties</a> to control the output.</p><p>The default is generate <em>everything</em> supported by the specific library. Once you enable a feature, it will restrict the contents generated:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only models</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only apis</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property apis</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only supporting files</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property supportingFiles</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate models and supporting files</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models,supportingFiles</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>To control the specific files being generated, you can pass a CSV list of what you want:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate the User and Pet models only</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models="User:Pet"</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate the User model and the supportingFile `StringUtil.java`:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models=User,supportingFiles=StringUtil.java</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>To control generation of docs and tests for api and models, pass false to the option. For api, these options are <code>--global-property apiTests=false,apiDocs=false</code>. For models, <code>--global-property modelTests=false,modelDocs=false</code>.
|
|
These options default to true and don't limit the generation of the feature options listed above (like <code>--global-property api</code>):</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only models (with tests and documentation)</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only models (with tests but no documentation)</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models,modelDocs=false</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only User and Pet models (no tests and no documentation)</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property models="User:Pet",modelTests=false</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only apis (without tests)</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property apis,apiTests=false</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># generate only apis (modelTests option is ignored)</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property apis,modelTests=false</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>When using selective generation, <em>only</em> the templates needed for the specific generation will be used.</p><p>To skip models defined as the form parameters in "requestBody", please use <code>skipFormModel</code> (default to <code>true</code>) (this option is introduced at v3.2.2 and <code>true</code> by default starting from v5.x).</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">--global-property skipFormModel=true</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>This option will be helpful to skip model generation due to the form parameter, which is defined differently in OAS3 as there's no form parameter in OAS3</p><h2><a aria-hidden="true" tabindex="-1" class="anchor" id="ignore-file-format"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#ignore-file-format" title="Direct link to heading">#</a>Ignore file format</h2><p>OpenAPI Generator supports a <code>.openapi-generator-ignore</code> file, similar to <code>.gitignore</code> or <code>.dockerignore</code> you're probably already familiar with.</p><p>The ignore file allows for better control over overwriting existing files than the <code>--skip-overwrite</code> flag. With the ignore file, you can specify individual files or directories can be ignored. This can be useful, for example if you only want a subset of the generated code.</p><p>Examples:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain"># OpenAPI Generator Ignore</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># Lines beginning with a # are comments</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># This should match build.sh located anywhere.</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">build.sh</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># Matches build.sh in the root</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">/build.sh</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># Exclude all recursively</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">docs/**</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># Explicitly allow files excluded by other rules</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">!docs/UserApi.md</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># Recursively exclude directories named Api</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># You can't negate files below this directory.</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">src/**/Api/</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># When this file is nested under /Api (excluded above),</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># this rule is ignored because parent directory is excluded by previous rule.</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">!src/**/PetApiTests.cs</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"># Exclude a single, nested file explicitly</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">src/Org.OpenAPITools.Test/Model/AnimalFarmTests.cs</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>The <code>.openapi-generator-ignore</code> file must exist in the root of the output directory.</p><p>Upon first code generation, you may also pass the CLI option <code>--ignore-file-override=/path/to/ignore_file</code> for greater control over generated outputs. Note that this is a complete override, and will override the <code>.openapi-generator-ignore</code> file in an output directory when regenerating code.</p><p>Editor support for <code>.openapi-generator-ignore</code> files is available in IntelliJ via the <a href="https://plugins.jetbrains.com/plugin/7495--ignore">.ignore plugin</a>.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor" id="customizing-the-generator"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#customizing-the-generator" title="Direct link to heading">#</a>Customizing the generator</h2><p>There are different aspects of customizing the code generator beyond just creating or modifying templates. Each language has a supporting configuration file to handle different type mappings, etc:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">$ ls -1 modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">AbstractJavaJAXRSServerCodegen.java</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">AbstractTypeScriptClientCodegen.java</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">... (results omitted)</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">TypeScriptAngularClientCodegen.java</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain">TypeScriptNodeClientCodegen.java</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Each of these files creates reasonable defaults so you can get running quickly. But if you want to configure package names, prefixes, model folders, etc. you can use a json config file to pass the values.</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -g java \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -o samples/client/petstore/java \</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> -c path/to/config.json</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>and <code>config.json</code> contains the following as an example:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-json codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token property">"apiPackage"</span><span class="token plain"> </span><span class="token operator">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"petstore"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>You can use also <code>config.yml</code> with following equivalent example:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-yaml codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token key atrule">apiPackage</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"petstore"</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Supported config options can be different per language. Running <code>config-help -g {lang}</code> will show available options.
|
|
<strong>These options are applied via configuration file (e.g. config.json or config.yml) or by passing them with <code>-p {optionName}={optionValue}</code></strong>. (If <code>-p {optionName}</code> does not work, please open a <a href="https://github.com/openapitools/openapi-generator/issues/new">ticket</a> and we'll look into it)</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-sh codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar config-help -g java</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Output</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">CONFIG OPTIONS</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> modelPackage</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> package </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> generated models</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> apiPackage</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> package </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> generated api classes</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">..</span><span class="token punctuation" style="color:rgb(248, 248, 242)">..</span><span class="token punctuation" style="color:rgb(248, 248, 242)">..</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">results omitted</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> library</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> library template </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">sub-template</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> to use:</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> jersey1 - HTTP client: Jersey client </span><span class="token number">1.18</span><span class="token plain">. JSON processing: Jackson </span><span class="token number">2.4</span><span class="token plain">.2</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> jersey2 - HTTP client: Jersey client </span><span class="token number">2.6</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> feign - HTTP client: Netflix Feign </span><span class="token number">8.1</span><span class="token plain">.1. JSON processing: Jackson </span><span class="token number">2.6</span><span class="token plain">.3</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> okhttp-gson </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">default</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"> - HTTP client: OkHttp </span><span class="token number">2.4</span><span class="token plain">.0. JSON processing: Gson </span><span class="token number">2.3</span><span class="token plain">.1</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> retrofit - HTTP client: OkHttp </span><span class="token number">2.4</span><span class="token plain">.0. JSON processing: Gson </span><span class="token number">2.3</span><span class="token plain">.1 </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">Retrofit </span><span class="token number">1.9</span><span class="token plain">.0</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> retrofit2 - HTTP client: OkHttp </span><span class="token number">2.5</span><span class="token plain">.0. JSON processing: Gson </span><span class="token number">2.4</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">(</span><span class="token plain">Retrofit </span><span class="token number">2.0</span><span class="token plain">.0-beta2</span><span class="token punctuation" style="color:rgb(248, 248, 242)">)</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> google-api-client - HTTP client: google-api-client </span><span class="token number">1.23</span><span class="token plain">.0. JSON processing: Jackson </span><span class="token number">2.8</span><span class="token plain">.9</span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> rest-assured - HTTP client: rest-assured </span><span class="token builtin class-name" style="color:rgb(189, 147, 249)">:</span><span class="token plain"> </span><span class="token number">4.3</span><span class="token plain">.0. JSON processing: Gson </span><span class="token number">2.8</span><span class="token plain">.6. Only </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">for</span><span class="token plain"> Java8</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Your config file for Java can look like</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-json codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token property">"groupId"</span><span class="token operator">:</span><span class="token string" style="color:rgb(255, 121, 198)">"com.my.company"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token property">"artifactId"</span><span class="token operator">:</span><span class="token string" style="color:rgb(255, 121, 198)">"MyClient"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token property">"artifactVersion"</span><span class="token operator">:</span><span class="token string" style="color:rgb(255, 121, 198)">"1.2.0"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">,</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token property">"library"</span><span class="token operator">:</span><span class="token string" style="color:rgb(255, 121, 198)">"feign"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Or if you prefer yaml format it can look like</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-yaml codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token key atrule">groupId</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"com.my.company"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">artifactId</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"MyClient"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">artifactVersion</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"1.2.0"</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token key atrule">library</span><span class="token punctuation" style="color:rgb(248, 248, 242)">:</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"feign"</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>For all the unspecified options default values will be used.</p><p>Another way to override default options is to extend the config class for the specific language.
|
|
To change, for example, the prefix for the Objective-C generated files, simply subclass the <code>ObjcClientCodegen.java</code>:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-java codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">package</span><span class="token plain"> </span><span class="token namespace">com</span><span class="token namespace punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token namespace">mycompany</span><span class="token namespace punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token namespace">openapitools</span><span class="token namespace punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token namespace">codegen</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">import</span><span class="token plain"> </span><span class="token namespace">org</span><span class="token namespace punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token namespace">openapitools</span><span class="token namespace punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token namespace">codegen</span><span class="token namespace punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token namespace">languages</span><span class="token punctuation" style="color:rgb(248, 248, 242)">.</span><span class="token plain">*</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain" style="display:inline-block"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">public</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">class</span><span class="token plain"> </span><span class="token class-name">MyObjcCodegen</span><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">extends</span><span class="token plain"> </span><span class="token class-name">ObjcClientCodegen</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token keyword" style="color:rgb(189, 147, 249);font-style:italic">static</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">{</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> PREFIX </span><span class="token operator">=</span><span class="token plain"> </span><span class="token string" style="color:rgb(255, 121, 198)">"HELLO"</span><span class="token punctuation" style="color:rgb(248, 248, 242)">;</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"> </span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span><span class="token plain"></span></div><div class="token-line" style="color:#F8F8F2"><span class="token plain"></span><span class="token punctuation" style="color:rgb(248, 248, 242)">}</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>and specify the <code>classname</code> when running the generator:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">-g com.mycompany.openapitools.codegen.MyObjcCodegen</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Your subclass will now be loaded and overrides the <code>PREFIX</code> value in the superclass.</p><h2><a aria-hidden="true" tabindex="-1" class="anchor" id="bringing-your-own-models"></a><a aria-hidden="true" tabindex="-1" class="hash-link" href="#bringing-your-own-models" title="Direct link to heading">#</a>Bringing your own models</h2><p>Sometimes you don't want a model generated. In this case, you can simply specify an import mapping to tell
|
|
the codegen what <em>not</em> to create. When doing this, every location that references a specific model will
|
|
refer back to your classes. Note, this may not apply to all languages...</p><p>To specify an import mapping, use the <code>--import-mappings</code> argument and specify the model-to-import logic as such:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">--import-mappings </span><span class="token assign-left variable" style="color:rgb(189, 147, 249);font-style:italic">Pet</span><span class="token operator">=</span><span class="token plain">my.models.MyPet</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>Or for multiple mappings:</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">--import-mappings </span><span class="token assign-left variable" style="color:rgb(189, 147, 249);font-style:italic">Pet</span><span class="token operator">=</span><span class="token plain">my.models.MyPet,Order</span><span class="token operator">=</span><span class="token plain">my.models.MyOrder</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre><p>or</p><pre class="mdxCodeBlock_iHAB"><div class="codeBlockWrapper_2QGZ"><pre class="prism-code language-bash codeBlock_19pQ" style="color:#F8F8F2;background-color:#282A36"><div class="token-line" style="color:#F8F8F2"><span class="token plain">--import-mappings </span><span class="token assign-left variable" style="color:rgb(189, 147, 249);font-style:italic">Pet</span><span class="token operator">=</span><span class="token plain">my.models.MyPet --import-mappings </span><span class="token assign-left variable" style="color:rgb(189, 147, 249);font-style:italic">Order</span><span class="token operator">=</span><span class="token plain">my.models.MyOrder</span></div></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_1BYj">Copy</button></div></pre></div></article><div class="margin-vert--xl"><div class="row"><div class="col"><a href="https://github.com/OpenAPITools/openapi-generator/edit/master/website/../docs/customization.md" target="_blank" rel="noreferrer noopener"><svg fill="currentColor" height="1.2em" width="1.2em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 40 40" style="margin-right:0.3em;vertical-align:sub"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col text--right"><em><small>Last updated on <time datetime="2021-11-20T17:25:45.000Z" class="docLastUpdatedAt_1sqk">2021-11-20</time> by <strong>Kevin Chen</strong></small></em></div></div></div><div class="margin-vert--lg"><nav class="pagination-nav"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/docs/templating"><h5 class="pagination-nav__link--sublabel">Previous</h5><h4 class="pagination-nav__link--label">« Using Templates</h4></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/docs/debugging"><h5 class="pagination-nav__link--sublabel">Next</h5><h4 class="pagination-nav__link--label">Debugging »</h4></a></div></nav></div></div></div><div class="col col--3"><div class="tableOfContents_TbNY"><ul class="contents contents__left-border"><li><a href="#user-defined-templates" class="contents__link">User-defined Templates</a></li><li><a href="#custom-generator-and-template" class="contents__link">Custom Generator (and Template)</a><ul><li><a href="#use-your-new-generator-with-the-cli" class="contents__link">Use your new generator with the CLI</a></li><li><a href="#use-your-new-generator-with-the-maven-plugin" class="contents__link">Use your new generator with the maven plugin</a></li></ul></li><li><a href="#selective-generation" class="contents__link">Selective generation</a></li><li><a href="#ignore-file-format" class="contents__link">Ignore file format</a></li><li><a href="#customizing-the-generator" class="contents__link">Customizing the generator</a></li><li><a href="#bringing-your-own-models" class="contents__link">Bringing your own models</a></li></ul></div></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container"><div class="row footer__links"><div class="col footer__col"><h4 class="footer__title">Docs</h4><ul class="footer__items"><li class="footer__item"><a aria-current="page" class="footer__link-item active" href="/docs/customization">Customizing Generators</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/installation">Installation</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/integrations">Workflow Integrations</a></li></ul></div><div class="col footer__col"><h4 class="footer__title">Community</h4><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/users">User Showcase</a></li><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://stackoverflow.com/questions/tagged/openapi-generator">Stack Overflow</a></li><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://join.slack.com/t/openapi-generator/shared_invite/enQtNzAyNDMyOTU0OTE1LTY5ZDBiNDI5NzI5ZjQ1Y2E5OWVjMjZkYzY1ZGM2MWQ4YWFjMzcyNDY5MGI4NjQxNDBiMTlmZTc5NjY2ZTQ5MGM">Chat Room</a></li><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://twitter.com/oas_generator">Twitter</a></li></ul></div><div class="col footer__col"><h4 class="footer__title">More</h4><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/blog">Blog</a></li><li class="footer__item"><a class="footer__link-item" target="_blank" rel="noopener noreferrer" href="https://github.com/OpenAPITools/openapi-generator">GitHub</a></li></ul></div></div><div class="text--center"><div class="margin-bottom--sm"><a href="https://openapi-generator.tech/" target="_blank" rel="noopener noreferrer" class="footerLogoLink_1Wg7"><img class="footer__logo" alt="OpenAPI Tools" src="/img/mono-logo.svg"></a></div>Copyright © 2021 OpenAPI-Generator Contributors (https://openapi-generator.tech)</div></div></footer>
|
|
</div>
|
|
|
|
<script src="/styles.38be54b8.js"></script>
|
|
|
|
<script src="/runtime~main.f7c11631.js"></script>
|
|
|
|
<script src="/main.a437a66b.js"></script>
|
|
|
|
<script src="/1.df107477.js"></script>
|
|
|
|
<script src="/2.575ca174.js"></script>
|
|
|
|
<script src="/3.eada3617.js"></script>
|
|
|
|
<script src="/1be78505.3e977af1.js"></script>
|
|
|
|
<script src="/20ac7829.be2ad927.js"></script>
|
|
|
|
<script src="/17896441.60782a44.js"></script>
|
|
|
|
<script src="/b6a32428.154824ff.js"></script>
|
|
|
|
|
|
</body>
|
|
</html> |