mirror of
https://github.com/OpenAPITools/openapi-generator.git
synced 2025-05-12 20:50:55 +00:00
27 lines
39 KiB
HTML
27 lines
39 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-contributing">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v2.3.1">
|
||
<title data-rh="true">Guidelines For Contributing | OpenAPI Generator</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://openapi-generator.tech/img/docusaurus.png"><meta data-rh="true" name="twitter:image" content="https://openapi-generator.tech/img/docusaurus.png"><meta data-rh="true" property="og:url" content="https://openapi-generator.tech/docs/contributing"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Guidelines For Contributing | OpenAPI Generator"><meta data-rh="true" name="description" content="Before submitting an issue"><meta data-rh="true" property="og:description" content="Before submitting an issue"><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="canonical" href="https://openapi-generator.tech/docs/contributing"><link data-rh="true" rel="alternate" href="https://openapi-generator.tech/docs/contributing" hreflang="en"><link data-rh="true" rel="alternate" href="https://openapi-generator.tech/docs/contributing" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://51ITDG8FYN-dsn.algolia.net" crossorigin="anonymous"><link rel="alternate" type="application/rss+xml" href="/blog/rss.xml" title="OpenAPI Generator RSS Feed">
|
||
<link rel="alternate" type="application/atom+xml" href="/blog/atom.xml" title="OpenAPI Generator Atom Feed">
|
||
|
||
<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="search" type="application/opensearchdescription+xml" title="OpenAPI Generator" href="/opensearch.xml">
|
||
<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><link rel="stylesheet" href="/assets/css/styles.fcd3a3ce.css">
|
||
<link rel="preload" href="/assets/js/runtime~main.44b51cbd.js" as="script">
|
||
<link rel="preload" href="/assets/js/main.36bb184f.js" as="script">
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
|
||
<div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/mono-logo.svg" alt="OpenAPI Tools logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/mono-logo.svg" alt="OpenAPI Tools logo" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">OpenAPI Generator</b></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 href="https://api.openapi-generator.tech" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">API</a></div><div class="navbar__items navbar__items--right"><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/installation">Getting Started</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/templating">Extending</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" href="/docs/contributing">Contributing</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/contributing">Guidelines</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/code-of-conduct">Code of Conduct</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contribute-building">Building the code</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/new-generator">Create a New Generator</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/roadmap">About</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/release-summary">Releases</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/generators">API</a></div></li></ul></nav></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Contributing</span><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Guidelines</span><meta itemprop="position" content="2"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Guidelines For Contributing</h1></header><h2 class="anchor anchorWithStickyNavbar_LWe7" id="before-submitting-an-issue">Before submitting an issue<a href="#before-submitting-an-issue" class="hash-link" aria-label="Direct link to Before submitting an issue" title="Direct link to Before submitting an issue"></a></h2><ul><li>If you're not using the latest master to generate API clients or server stubs, please give it another try by pulling the latest master as the issue may have already been addressed. Ref: <a href="https://github.com/openapitools/openapi-generator#getting-started" target="_blank" rel="noopener noreferrer">Getting Started</a></li><li>Search the <a href="https://github.com/openapitools/openapi-generator/issues" target="_blank" rel="noopener noreferrer">open issue</a> and <a href="https://github.com/openapitools/openapi-generator/issues?q=is%3Aissue+is%3Aclosed" target="_blank" rel="noopener noreferrer">closed issue</a> to ensure no one else has reported something similar before.</li><li>File an <a href="https://github.com/openapitools/openapi-generator/issues/new" target="_blank" rel="noopener noreferrer">issue ticket</a> by providing all the required information. Failure to provide enough detail may result in slow response from the community.</li><li>Test with the latest master by building the JAR locally to see if the issue has already been addressed.</li><li>You can also make a suggestion or ask a question by opening an "issue".</li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="before-submitting-a-pr">Before submitting a PR<a href="#before-submitting-a-pr" class="hash-link" aria-label="Direct link to Before submitting a PR" title="Direct link to Before submitting a PR"></a></h2><ul><li>Search the <a href="https://github.com/openapitools/openapi-generator/issues" target="_blank" rel="noopener noreferrer">open issue</a> to ensure no one else has reported something similar and no one is actively working on similar proposed change.</li><li>If no one has suggested something similar, open an <a href="https://github.com/openapitools/openapi-generator/issues" target="_blank" rel="noopener noreferrer">"issue"</a> with your suggestion to gather feedback from the community.</li><li>If you're adding a new option to a generator, please consider using the <code>-t</code> option with customized templates instead or start a discussion first by opening an issue as we want to avoid adding too many options to the generator.</li><li>It's recommended to <strong>create a new git branch</strong> for the change so that the merge commit message looks nicer in the commit history.</li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="how-to-contribute">How to contribute<a href="#how-to-contribute" class="hash-link" aria-label="Direct link to How to contribute" title="Direct link to How to contribute"></a></h2><h3 class="anchor anchorWithStickyNavbar_LWe7" id="git">git<a href="#git" class="hash-link" aria-label="Direct link to git" title="Direct link to git"></a></h3><p>If you're new to git, you may find the following FAQs useful:</p><p><a href="https://github.com/openapitools/openapi-generator/wiki/FAQ#git" target="_blank" rel="noopener noreferrer">https://github.com/openapitools/openapi-generator/wiki/FAQ#git</a></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="branches">Branches<a href="#branches" class="hash-link" aria-label="Direct link to Branches" title="Direct link to Branches"></a></h3><p>Please file the pull request against the correct branch, e.g. <code>master</code> for non-breaking changes. See the <a href="https://github.com/OpenAPITools/openapi-generator/wiki/Git-Branches" target="_blank" rel="noopener noreferrer">Git Branches</a> page for more information.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="code-generators">Code generators<a href="#code-generators" class="hash-link" aria-label="Direct link to Code generators" title="Direct link to Code generators"></a></h3><p>All the code generators can be found in <a href="https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/main/java/org/openapitools/codegen/languages" target="_blank" rel="noopener noreferrer">modules/openapi-generator/src/main/java/org/openapitools/codegen/languages</a></p><p>If you want to add a new generator, follow the <a href="https://openapi-generator.tech/docs/new-generator" target="_blank" rel="noopener noreferrer">new-generator</a> guide.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="templates">Templates<a href="#templates" class="hash-link" aria-label="Direct link to Templates" title="Direct link to Templates"></a></h3><p>All the templates (<a href="https://mustache.github.io/" target="_blank" rel="noopener noreferrer">mustache</a>) can be found in <a href="https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources" target="_blank" rel="noopener noreferrer">modules/openapi-generator/src/main/resources</a>.</p><p>For a list of variables available in the template, please refer to this <a href="https://github.com/openapitools/openapi-generator/wiki/Mustache-Template-Variables" target="_blank" rel="noopener noreferrer">page</a></p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="style-guide">Style guide<a href="#style-guide" class="hash-link" aria-label="Direct link to Style guide" title="Direct link to Style guide"></a></h3><p>Code change should conform to the programming style guide of the respective languages:</p><ul><li>Ada: <a href="https://en.wikibooks.org/wiki/Ada_Style_Guide/Source_Code_Presentation" target="_blank" rel="noopener noreferrer">https://en.wikibooks.org/wiki/Ada_Style_Guide/Source_Code_Presentation</a></li><li>Android: <a href="https://source.android.com/source/code-style.html" target="_blank" rel="noopener noreferrer">https://source.android.com/source/code-style.html</a></li><li>Bash: <a href="https://github.com/bahamas10/bash-style-guide" target="_blank" rel="noopener noreferrer">https://github.com/bahamas10/bash-style-guide</a></li><li>C#: <a href="https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx" target="_blank" rel="noopener noreferrer">https://msdn.microsoft.com/en-us/library/vstudio/ff926074.aspx</a></li><li>C++: <a href="https://google.github.io/styleguide/cppguide.html" target="_blank" rel="noopener noreferrer">https://google.github.io/styleguide/cppguide.html</a></li><li>C++ (Tizen): <a href="https://wiki.tizen.org/Native_Platform_Coding_Idiom_and_Style_Guide#C.2B.2B_Coding_Style" target="_blank" rel="noopener noreferrer">https://wiki.tizen.org/Native_Platform_Coding_Idiom_and_Style_Guide#C.2B.2B_Coding_Style</a></li><li>C++ (Unreal Engine 4): <a href="https://docs.unrealengine.com/en-US/ProductionPipelines/DevelopmentSetup/CodingStandard/index.html" target="_blank" rel="noopener noreferrer">https://docs.unrealengine.com/en-US/ProductionPipelines/DevelopmentSetup/CodingStandard/index.html</a></li><li>Clojure: <a href="https://github.com/bbatsov/clojure-style-guide" target="_blank" rel="noopener noreferrer">https://github.com/bbatsov/clojure-style-guide</a></li><li>Crystal: <a href="https://crystal-lang.org/reference/conventions/coding_style.html" target="_blank" rel="noopener noreferrer">https://crystal-lang.org/reference/conventions/coding_style.html</a></li><li>Dart: <a href="https://www.dartlang.org/guides/language/effective-dart/style" target="_blank" rel="noopener noreferrer">https://www.dartlang.org/guides/language/effective-dart/style</a></li><li>Eiffel: <a href="https://www.eiffel.org/doc/eiffel/Coding%20Standards" target="_blank" rel="noopener noreferrer">https://www.eiffel.org/doc/eiffel/Coding%20Standards</a></li><li>Elixir: <a href="https://github.com/christopheradams/elixir_style_guide" target="_blank" rel="noopener noreferrer">https://github.com/christopheradams/elixir_style_guide</a></li><li>Erlang: <a href="https://github.com/inaka/erlang_guidelines" target="_blank" rel="noopener noreferrer">https://github.com/inaka/erlang_guidelines</a></li><li>Go: <a href="https://github.com/golang/go/wiki/CodeReviewComments" target="_blank" rel="noopener noreferrer">https://github.com/golang/go/wiki/CodeReviewComments</a></li><li>Groovy: <a href="http://groovy-lang.org/style-guide.html" target="_blank" rel="noopener noreferrer">http://groovy-lang.org/style-guide.html</a></li><li>Haskell: <a href="https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md" target="_blank" rel="noopener noreferrer">https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md</a></li><li>Java: <a href="https://google.github.io/styleguide/javaguide.html" target="_blank" rel="noopener noreferrer">https://google.github.io/styleguide/javaguide.html</a></li><li>JavaScript: <a href="https://github.com/airbnb/javascript/" target="_blank" rel="noopener noreferrer">https://github.com/airbnb/javascript/</a></li><li>Julia: <a href="https://docs.julialang.org/en/v1/manual/style-guide/" target="_blank" rel="noopener noreferrer">https://docs.julialang.org/en/v1/manual/style-guide/</a></li><li>Kotlin: <a href="https://kotlinlang.org/docs/reference/coding-conventions.html" target="_blank" rel="noopener noreferrer">https://kotlinlang.org/docs/reference/coding-conventions.html</a></li><li>ObjC: <a href="https://github.com/NYTimes/objective-c-style-guide" target="_blank" rel="noopener noreferrer">https://github.com/NYTimes/objective-c-style-guide</a></li><li>Perl: <a href="http://perldoc.perl.org/perlstyle.html" target="_blank" rel="noopener noreferrer">http://perldoc.perl.org/perlstyle.html</a></li><li>PHP: <a href="https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-12-extended-coding-style-guide.md" target="_blank" rel="noopener noreferrer">https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-12-extended-coding-style-guide.md</a></li><li>PowerShell: <a href="https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx" target="_blank" rel="noopener noreferrer">https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx</a></li><li>Python: <a href="https://www.python.org/dev/peps/pep-0008/" target="_blank" rel="noopener noreferrer">https://www.python.org/dev/peps/pep-0008/</a></li><li>R: <a href="https://google.github.io/styleguide/Rguide.xml" target="_blank" rel="noopener noreferrer">https://google.github.io/styleguide/Rguide.xml</a></li><li>Ruby: <a href="https://github.com/bbatsov/ruby-style-guide" target="_blank" rel="noopener noreferrer">https://github.com/bbatsov/ruby-style-guide</a></li><li>Rust: <a href="https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md" target="_blank" rel="noopener noreferrer">https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md</a> (the default <a href="https://github.com/rust-lang-nursery/rustfmt" target="_blank" rel="noopener noreferrer">rustfmt</a> configuration)</li><li>Scala: <a href="http://docs.scala-lang.org/style/" target="_blank" rel="noopener noreferrer">http://docs.scala-lang.org/style/</a></li><li>Swift: <a href="https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/Swift_Programming_Language/TheBasics.html" target="_blank" rel="noopener noreferrer">Apple Developer</a></li><li>TypeScript: <a href="https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines" target="_blank" rel="noopener noreferrer">https://github.com/Microsoft/TypeScript/wiki/Coding-guidelines</a></li><li>Xojo: <a href="https://documentation.xojo.com/topics/code_management/coding_guidelines.html" target="_blank" rel="noopener noreferrer">https://documentation.xojo.com/topics/code_management/coding_guidelines.html</a></li></ul><p>For other languages, feel free to suggest.</p><p>You may find the current code base not 100% conform to the coding style and we welcome contributions to fix those.</p><p>For <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#vendorExtensions" target="_blank" rel="noopener noreferrer">Vendor Extensions</a>, please follow the naming convention below:</p><ul><li>For general vendor extension, use lower case and hyphen. e.g. <code>x-is-unique</code>, <code>x-content-type</code></li><li>For language-specified vendor extension, put it in the form of <code>x-{lang}-{extension-name}</code>. e.g. <code>x-objc-operation-id</code>, <code>x-java-feign-retry-limit</code></li><li>For a list of existing vendor extensions in use, please refer to <a href="https://github.com/openapitools/openapi-generator/wiki/Vendor-Extensions" target="_blank" rel="noopener noreferrer">https://github.com/openapitools/openapi-generator/wiki/Vendor-Extensions</a>. If you've added new vendor extensions as part of your PR, please update the wiki page.</li></ul><h3 class="anchor anchorWithStickyNavbar_LWe7" id="building">Building<a href="#building" class="hash-link" aria-label="Direct link to Building" title="Direct link to Building"></a></h3><p>The <code>openapi-generator-cli</code> can be built using the following command. This will generate the <code>openapi-generator-cli.jar</code> in the <code>modules/openapi-generator-cli/target</code> directory without running the tests and generating the Javadocs.</p><div class="language-shell codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-shell codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">./mvnw clean </span><span class="token function" style="color:rgb(80, 250, 123)">install</span><span class="token plain"> -DskipTests -Dmaven.javadoc.skip</span><span class="token operator">=</span><span class="token plain">true</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>Or on Windows:</p><div class="language-shell codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-shell codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">mvnw.cmd clean </span><span class="token function" style="color:rgb(80, 250, 123)">install</span><span class="token plain"> -DskipTests -Dmaven.javadoc.skip</span><span class="token operator">=</span><span class="token plain">true</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>The binary can run via <code>java -jar</code>. For example:</p><div class="language-shell codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-shell codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar </span><span class="token builtin class-name" style="color:rgb(189, 147, 249)">help</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg class="copyButtonIcon_y97N" viewBox="0 0 24 24"><path d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg class="copyButtonSuccessIcon_LjdS" viewBox="0 0 24 24"><path d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="testing">Testing<a href="#testing" class="hash-link" aria-label="Direct link to Testing" title="Direct link to Testing"></a></h3><p>To add test cases (optional) covering the change in the code generator, please refer to <a href="https://github.com/openapitools/openapi-generator/tree/master/modules/openapi-generator/src/test/java/org/openapitools/codegen" target="_blank" rel="noopener noreferrer">modules/openapi-generator/src/test/java/org/openapitools/codegen</a></p><p>To test the templates, please perform the following:</p><ul><li>Update the Petstore sample by running the shell scripts under the <code>bin</code> folder. For example, run <code>./bin/generate-samples.sh ./bin/configs/python*</code> to update the Python-related samples under <a href="https://github.com/openapitools/openapi-generator/tree/master/samples" target="_blank" rel="noopener noreferrer"><code>samples</code></a>. For Windows, please install <a href="https://gitforwindows.org/" target="_blank" rel="noopener noreferrer">GIT bash</a>. (If you find that there are new files generated or unexpected changes as a result of the update, that's not unusual as the test cases are added to the OpenAPI spec from time to time. If you've questions or concerns, please open a ticket to start a discussion)</li><li>During development, it can be helpful to quickly regenerate the samples without recompiling all of openapi-generator, e.g. when you have only updated the mustache templates. This can be done by passing the <code>-t</code> parameter: <code>-t modules/openapi-generator/src/main/resources/python</code>.</li><li>Run the tests in the sample folder using maven <code>mvn integration-test -f /path/to/pom.xml</code>, e.g. <code>mvn integration-test -f samples/client/petstore/python/pom.xml</code>. (some languages may not contain unit testing for Petstore and we're looking for contribution from the community to implement those tests). <strong>Please notice:</strong> you must run a local instance of the Petstore server in order to perform the tests, as running them against petstore.swagger.io is not supported anymore. Please refer to item 3 of <a href="https://github.com/OpenAPITools/openapi-generator/wiki/Integration-Tests#how-to-add-integration-tests-for-new-petstore-samples" target="_blank" rel="noopener noreferrer">Integration Tests - How to add integration tests for new Petstore samples</a> to learn how to quickly configure and run it.</li><li>Finally, git commit the updated samples files: <code>git commit -a</code> (<code>git add -A</code> if added files with new test cases)</li><li>For new test cases, please add to the <a href="https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator/src/test/resources/3_0/petstore-with-fake-endpoints-models-for-testing.yaml" target="_blank" rel="noopener noreferrer">Fake Petstore spec</a></li></ul><p>To start the CI tests, you can:</p><ul><li>Run <code>mvn verify -Psamples</code>, assuming you have all the required tools installed to run tests for different languages.</li><li>Leverage <a href="http://travis-ci.org" target="_blank" rel="noopener noreferrer">http://travis-ci.org</a> to run the CI tests by adding your own openapi-generator repository.</li><li>Run some of the CI tests in your local workspace.</li></ul><p>See <a href="https://github.com/OpenAPITools/openapi-generator/wiki/Integration-Tests" target="_blank" rel="noopener noreferrer">OpenAPI Tools wiki</a> for more information about the integration tests.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="tips">Tips<a href="#tips" class="hash-link" aria-label="Direct link to Tips" title="Direct link to Tips"></a></h3><ul><li>Smaller changes are easier to review</li><li>[Optional]<!-- --> For bug fixes, provide a OpenAPI Spec to repeat the issue so that the reviewer can use it to confirm the fix</li><li>Add test case(s) to cover the change</li><li>Document the fix in the code to make the code more readable</li><li>Make sure test cases passed after the change (one way is to leverage <a href="https://travis-ci.org/" target="_blank" rel="noopener noreferrer">https://travis-ci.org/</a> to run the CI tests)</li><li>File a PR with meaningful title, description and commit messages</li><li>Make sure the option "Allow edits from maintainers" in the PR is selected so that the maintainers can update your PRs with minor fixes, if needed.</li><li>Recommended git settings<ul><li><code>git config core.autocrlf input</code> to tell Git convert CRLF to LF on commit but not the other way around</li></ul></li><li>To close an issue (e.g. issue 1542) automatically after a PR is merged, use keywords "fix", "close", "resolve" in the PR description, e.g. <code>fix #1542</code>. (Ref: <a href="https://help.github.com/articles/closing-issues-using-keywords/" target="_blank" rel="noopener noreferrer">closing issues using keywords</a>)</li></ul></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/OpenAPITools/openapi-generator/edit/master/website/../docs/contributing.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><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 lastUpdated_vwxv"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2024-04-24T07:34:02.000Z">Apr 24, 2024</time></b> by <b>William Cheng</b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/integrations"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Workflow Integrations</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/code-of-conduct"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Code of Conduct</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#before-submitting-an-issue" class="table-of-contents__link toc-highlight">Before submitting an issue</a></li><li><a href="#before-submitting-a-pr" class="table-of-contents__link toc-highlight">Before submitting a PR</a></li><li><a href="#how-to-contribute" class="table-of-contents__link toc-highlight">How to contribute</a><ul><li><a href="#git" class="table-of-contents__link toc-highlight">git</a></li><li><a href="#branches" class="table-of-contents__link toc-highlight">Branches</a></li><li><a href="#code-generators" class="table-of-contents__link toc-highlight">Code generators</a></li><li><a href="#templates" class="table-of-contents__link toc-highlight">Templates</a></li><li><a href="#style-guide" class="table-of-contents__link toc-highlight">Style guide</a></li><li><a href="#building" class="table-of-contents__link toc-highlight">Building</a></li><li><a href="#testing" class="table-of-contents__link toc-highlight">Testing</a></li><li><a href="#tips" class="table-of-contents__link toc-highlight">Tips</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" 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"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/users">User Showcase</a></li><li class="footer__item"><a href="https://stackoverflow.com/questions/tagged/openapi-generator" target="_blank" rel="noopener noreferrer" class="footer__link-item">Stack Overflow<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://join.slack.com/t/openapi-generator/shared_invite/zt-12jxxd7p2-XUeQM~4pzsU9x~eGLQqX2g" target="_blank" rel="noopener noreferrer" class="footer__link-item">Chat Room<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://twitter.com/oas_generator" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/blog">Blog</a></li><li class="footer__item"><a href="https://github.com/OpenAPITools/openapi-generator" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><a href="https://openapi-generator.tech/" rel="noopener noreferrer" class="footerLogoLink_BH7S"><img src="/img/mono-logo.svg" alt="OpenAPI Tools" class="themedImage_ToTc themedImage--light_HNdA footer__logo"><img src="/img/mono-logo.svg" alt="OpenAPI Tools" class="themedImage_ToTc themedImage--dark_i4oU footer__logo"></a></div><div class="footer__copyright">Copyright © 2025 OpenAPI-Generator Contributors (https://openapi-generator.tech)</div></div></div></footer></div>
|
||
<script src="/assets/js/runtime~main.44b51cbd.js"></script>
|
||
<script src="/assets/js/main.36bb184f.js"></script>
|
||
</body>
|
||
</html> |