From c16f7f0aade0b822f63534c4b33c4478c7287601 Mon Sep 17 00:00:00 2001 From: martin-mfg <2026226+martin-mfg@users.noreply.github.com> Date: Sat, 27 Apr 2024 09:35:49 +0200 Subject: [PATCH] better example of user defined supporting file (#18512) --- .../java-okhttp-user-defined-templates.yaml | 2 +- .../.openapi-generator/FILES | 1 - .../README.md | 184 --- .../info.md | 1357 ++--------------- 4 files changed, 127 insertions(+), 1417 deletions(-) delete mode 100644 samples/client/echo_api/java/okhttp-gson-user-defined-templates/README.md diff --git a/bin/configs/java-okhttp-user-defined-templates.yaml b/bin/configs/java-okhttp-user-defined-templates.yaml index 495cae7bdfcf..650c2dc1b195 100644 --- a/bin/configs/java-okhttp-user-defined-templates.yaml +++ b/bin/configs/java-okhttp-user-defined-templates.yaml @@ -6,7 +6,7 @@ templateDir: modules/openapi-generator/src/main/resources/Java additionalProperties: hideGenerationTimestamp: "true" files: - README.md: + README.mustache: destinationFilename: info.md api_doc.mustache: templateType: APIDocs diff --git a/samples/client/echo_api/java/okhttp-gson-user-defined-templates/.openapi-generator/FILES b/samples/client/echo_api/java/okhttp-gson-user-defined-templates/.openapi-generator/FILES index 0061d2762a1a..d4b634f6f4e3 100644 --- a/samples/client/echo_api/java/okhttp-gson-user-defined-templates/.openapi-generator/FILES +++ b/samples/client/echo_api/java/okhttp-gson-user-defined-templates/.openapi-generator/FILES @@ -1,7 +1,6 @@ .github/workflows/maven.yml .gitignore .travis.yml -README.md api/openapi.yaml build.gradle build.sbt diff --git a/samples/client/echo_api/java/okhttp-gson-user-defined-templates/README.md b/samples/client/echo_api/java/okhttp-gson-user-defined-templates/README.md deleted file mode 100644 index 61555e362393..000000000000 --- a/samples/client/echo_api/java/okhttp-gson-user-defined-templates/README.md +++ /dev/null @@ -1,184 +0,0 @@ -# openapi-java-client - -OpenAPI Petstore -- API version: 1.0.0 - - Generator version: 7.6.0-SNAPSHOT - -This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters. - - -*Automatically generated by the [OpenAPI Generator](https://openapi-generator.tech)* - - -## Requirements - -Building the API client library requires: -1. Java 1.8+ -2. Maven (3.8.3+)/Gradle (7.2+) - -## Installation - -To install the API client library to your local Maven repository, simply execute: - -```shell -mvn clean install -``` - -To deploy it to a remote Maven repository instead, configure the settings of the repository and execute: - -```shell -mvn clean deploy -``` - -Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information. - -### Maven users - -Add this dependency to your project's POM: - -```xml - - org.openapitools - openapi-java-client - 1.0.0 - compile - -``` - -### Gradle users - -Add this dependency to your project's build file: - -```groovy - repositories { - mavenCentral() // Needed if the 'openapi-java-client' jar has been published to maven central. - mavenLocal() // Needed if the 'openapi-java-client' jar has been published to the local maven repo. - } - - dependencies { - implementation "org.openapitools:openapi-java-client:1.0.0" - } -``` - -### Others - -At first generate the JAR by executing: - -```shell -mvn clean package -``` - -Then manually install the following JARs: - -* `target/openapi-java-client-1.0.0.jar` -* `target/lib/*.jar` - -## Getting Started - -Please follow the [installation](#installation) instruction and execute the following Java code: - -```java - -// Import classes: -import org.openapitools.client.ApiClient; -import org.openapitools.client.ApiException; -import org.openapitools.client.Configuration; -import org.openapitools.client.auth.*; -import org.openapitools.client.models.*; -import org.openapitools.client.api.PetApi; - -public class Example { - public static void main(String[] args) { - ApiClient defaultClient = Configuration.getDefaultApiClient(); - defaultClient.setBasePath("http://petstore.swagger.io/v2"); - - // Configure OAuth2 access token for authorization: petstore_auth - OAuth petstore_auth = (OAuth) defaultClient.getAuthentication("petstore_auth"); - petstore_auth.setAccessToken("YOUR ACCESS TOKEN"); - - PetApi apiInstance = new PetApi(defaultClient); - Pet pet = new Pet(); // Pet | Pet object that needs to be added to the store - try { - Pet result = apiInstance.addPet(pet); - System.out.println(result); - } catch (ApiException e) { - System.err.println("Exception when calling PetApi#addPet"); - System.err.println("Status code: " + e.getCode()); - System.err.println("Reason: " + e.getResponseBody()); - System.err.println("Response headers: " + e.getResponseHeaders()); - e.printStackTrace(); - } - } -} - -``` - -## Documentation for API Endpoints - -All URIs are relative to *http://petstore.swagger.io/v2* - -Class | Method | HTTP request | Description ------------- | ------------- | ------------- | ------------- -*PetApi* | [**addPet**](docs/PetApi.md#addPet) | **POST** /pet | Add a new pet to the store -*PetApi* | [**deletePet**](docs/PetApi.md#deletePet) | **DELETE** /pet/{petId} | Deletes a pet -*PetApi* | [**findPetsByStatus**](docs/PetApi.md#findPetsByStatus) | **GET** /pet/findByStatus | Finds Pets by status -*PetApi* | [**findPetsByTags**](docs/PetApi.md#findPetsByTags) | **GET** /pet/findByTags | Finds Pets by tags -*PetApi* | [**getPetById**](docs/PetApi.md#getPetById) | **GET** /pet/{petId} | Find pet by ID -*PetApi* | [**updatePet**](docs/PetApi.md#updatePet) | **PUT** /pet | Update an existing pet -*PetApi* | [**updatePetWithForm**](docs/PetApi.md#updatePetWithForm) | **POST** /pet/{petId} | Updates a pet in the store with form data -*PetApi* | [**uploadFile**](docs/PetApi.md#uploadFile) | **POST** /pet/{petId}/uploadImage | uploads an image -*StoreApi* | [**deleteOrder**](docs/StoreApi.md#deleteOrder) | **DELETE** /store/order/{orderId} | Delete purchase order by ID -*StoreApi* | [**getInventory**](docs/StoreApi.md#getInventory) | **GET** /store/inventory | Returns pet inventories by status -*StoreApi* | [**getOrderById**](docs/StoreApi.md#getOrderById) | **GET** /store/order/{orderId} | Find purchase order by ID -*StoreApi* | [**placeOrder**](docs/StoreApi.md#placeOrder) | **POST** /store/order | Place an order for a pet -*UserApi* | [**createUser**](docs/UserApi.md#createUser) | **POST** /user | Create user -*UserApi* | [**createUsersWithArrayInput**](docs/UserApi.md#createUsersWithArrayInput) | **POST** /user/createWithArray | Creates list of users with given input array -*UserApi* | [**createUsersWithListInput**](docs/UserApi.md#createUsersWithListInput) | **POST** /user/createWithList | Creates list of users with given input array -*UserApi* | [**deleteUser**](docs/UserApi.md#deleteUser) | **DELETE** /user/{username} | Delete user -*UserApi* | [**getUserByName**](docs/UserApi.md#getUserByName) | **GET** /user/{username} | Get user by user name -*UserApi* | [**loginUser**](docs/UserApi.md#loginUser) | **GET** /user/login | Logs user into the system -*UserApi* | [**logoutUser**](docs/UserApi.md#logoutUser) | **GET** /user/logout | Logs out current logged in user session -*UserApi* | [**updateUser**](docs/UserApi.md#updateUser) | **PUT** /user/{username} | Updated user - - -## Documentation for Models - - - [Category](docs/Category.md) - - [ModelApiResponse](docs/ModelApiResponse.md) - - [Order](docs/Order.md) - - [Pet](docs/Pet.md) - - [Tag](docs/Tag.md) - - [User](docs/User.md) - - - -## Documentation for Authorization - - -Authentication schemes defined for the API: - -### petstore_auth - -- **Type**: OAuth -- **Flow**: implicit -- **Authorization URL**: http://petstore.swagger.io/api/oauth/dialog -- **Scopes**: - - write:pets: modify pets in your account - - read:pets: read your pets - - -### api_key - -- **Type**: API key -- **API key parameter name**: api_key -- **Location**: HTTP header - - -## Recommendation - -It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues. - -## Author - - - diff --git a/samples/client/echo_api/java/okhttp-gson-user-defined-templates/info.md b/samples/client/echo_api/java/okhttp-gson-user-defined-templates/info.md index 84ce04142c02..61555e362393 100644 --- a/samples/client/echo_api/java/okhttp-gson-user-defined-templates/info.md +++ b/samples/client/echo_api/java/okhttp-gson-user-defined-templates/info.md @@ -1,1289 +1,184 @@ -

OpenAPI Generator

+# openapi-java-client +OpenAPI Petstore +- API version: 1.0.0 + - Generator version: 7.6.0-SNAPSHOT -
+This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters. -[![Stable releases in Maven Central](https://img.shields.io/maven-metadata/v/https/repo1.maven.org/maven2/org/openapitools/openapi-generator/maven-metadata.xml.svg)](http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.openapitools%22%20AND%20a%3A%22openapi-generator%22) -[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-orange)](./LICENSE) -[![Open Collective backers](https://img.shields.io/opencollective/backers/openapi_generator?color=orange&label=OpenCollective%20Backers)](https://opencollective.com/openapi_generator) -[![Join the Slack chat room](https://img.shields.io/badge/Slack-Join%20the%20chat%20room-orange)](https://join.slack.com/t/openapi-generator/shared_invite/zt-12jxxd7p2-XUeQM~4pzsU9x~eGLQqX2g) -[![Follow OpenAPI Generator Twitter account to get the latest update](https://img.shields.io/twitter/follow/oas_generator.svg?style=social&label=Follow)](https://twitter.com/oas_generator) -[![Contribute with Gitpod](https://img.shields.io/badge/Contribute%20with-Gitpod-908a85?logo=gitpod)](https://gitpod.io/#https://github.com/OpenAPITools/openapi-generator) -[![Conan Center](https://shields.io/conan/v/openapi-generator)](https://conan.io/center/recipes/openapi-generator) -[![Revved up by Develocity](https://img.shields.io/badge/Revved%20up%20by-Develocity-06A0CE?logo=Gradle&labelColor=02303A)](https://ge.openapi-generator.tech/scans) -
-
+*Automatically generated by the [OpenAPI Generator](https://openapi-generator.tech)* -[Master](https://github.com/OpenAPITools/openapi-generator/tree/master) (`7.6.0`): -[![Build Status](https://api.travis-ci.com/OpenAPITools/openapi-generator.svg?branch=master&status=passed)](https://app.travis-ci.com/github/OpenAPITools/openapi-generator/builds) -[![Integration Test2](https://circleci.com/gh/OpenAPITools/openapi-generator.svg?style=shield)](https://circleci.com/gh/OpenAPITools/openapi-generator) -[![Windows Test](https://ci.appveyor.com/api/projects/status/github/openapitools/openapi-generator?branch=master&svg=true&passingText=Windows%20Test%20-%20OK&failingText=Windows%20Test%20-%20Fails)](https://ci.appveyor.com/project/WilliamCheng/openapi-generator) -[![Bitrise](https://img.shields.io/bitrise/4a2b10a819d12b67/master?label=bitrise%3A%20Swift+4,5&token=859FMDR8QHwabCzwvZK6vQ)](https://app.bitrise.io/app/4a2b10a819d12b67) -
+## Requirements -
+Building the API client library requires: +1. Java 1.8+ +2. Maven (3.8.3+)/Gradle (7.2+) -:star::star::star: If you would like to contribute, please refer to [guidelines](CONTRIBUTING.md) and a list of [open tasks](https://github.com/openapitools/openapi-generator/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22). :star::star::star: +## Installation -:bangbang: To migrate from Swagger Codegen to OpenAPI Generator, please refer to the [migration guide](docs/migration-from-swagger-codegen.md) :bangbang: +To install the API client library to your local Maven repository, simply execute: -:notebook_with_decorative_cover: For more information, please refer to the [Wiki page](https://github.com/openapitools/openapi-generator/wiki) and [FAQ](https://github.com/openapitools/openapi-generator/wiki/FAQ) :notebook_with_decorative_cover: - -:notebook_with_decorative_cover: The eBook [A Beginner's Guide to Code Generation for REST APIs](https://gum.co/openapi_generator_ebook) is a good starting point for beginners :notebook_with_decorative_cover: - -:warning: If the OpenAPI spec, templates or any input (e.g. options, environment variables) is obtained from an untrusted source or environment, please make sure you've reviewed these inputs before using OpenAPI Generator to generate the API client, server stub or documentation to avoid potential security issues (e.g. [code injection](https://en.wikipedia.org/wiki/Code_injection)). For security vulnerabilities, please contact [team@openapitools.org](mailto:team@openapitools.org). :warning: - -:bangbang: Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI Generator) and "OpenAPI Generator" are not affiliated with OpenAPI Initiative (OAI) :bangbang: - -
- -## Sponsors - -If you find OpenAPI Generator useful for work, please consider asking your company to support this Open Source project by [becoming a sponsor](https://opencollective.com/openapi_generator). You can also individually sponsor the project by [becoming a backer](https://opencollective.com/openapi_generator). - -#### Thank you to our bronze sponsors! - -[![NamSor](https://openapi-generator.tech/img/companies/namsor.png)](https://www.namsor.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[![LightBow](https://openapi-generator.tech/img/companies/lightbow.png)](https://www.lightbow.net/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://docspring.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://datadoghq.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://cpl.thalesgroup.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.apideck.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.pexa.com.au/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.numary.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.onesignal.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.virtualansoftware.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.merge.dev/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.burkert.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.finbourne.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://bump.sh/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.bileto.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.bairesdev.com/sponsoring-open-source-projects/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://www.dmtech.de/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://adyen.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://fornex.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://runalloy.com/signup?utm_source=github&utm_medium=referral&utm_campaign=1524_openapigenerator) -[](https://ssstwitter.com/?utm_source=github&utm_medium=referral&utm_campaign=sponsor) -[](https://www.svix.com/?utm_source=openapi-generator&utm_medium=sponsorship&utm_campaign=oss-sponsorship) -[](https://litslink.com/services/artificial-intelligence?utm_source=openapi-generator&utm_medium=sponsorship&utm_campaign=oss-sponsorship) -[](https://designli.co?utm_source=openapi-generator&utm_medium=sponsorship&utm_campaign=oss-sponsorship) - - -#### Thank you GoDaddy for sponsoring the domain names, Linode for sponsoring the VPS, Checkly for sponsoring the API monitoring and Gradle for sponsoring Develocity - -[](https://www.godaddy.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[![Linode](https://www.linode.com/media/images/logos/standard/light/linode-logo_standard_light_small.png)](https://www.linode.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://checklyhq.com/?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) -[](https://gradle.org?utm_source=openapi_generator&utm_medium=github_webpage&utm_campaign=sponsor) - -## Overview - -OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an [OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification) (both 2.0 and 3.0 are supported). Currently, the following languages/frameworks are supported: - -| | Languages/Frameworks | -| -------------------------------- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **API clients** | **ActionScript**, **Ada**, **Apex**, **Bash**, **C**, **C#** (.net 2.0, 3.5 or later, .NET Standard 1.3 - 2.1, .NET Core 3.1, .NET 5.0. Libraries: RestSharp, GenericHost, HttpClient), **C++** (Arduino, cpp-restsdk, Qt5, Tizen, Unreal Engine 4), **Clojure**, **Crystal**, **Dart**, **Elixir**, **Elm**, **Eiffel**, **Erlang**, **Go**, **Groovy**, **Haskell** (http-client, Servant), **Java** (Apache HttpClient 4.x, Apache HttpClient 5.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured, Spring 5 Web Client, MicroProfile Rest Client, Helidon), **Jetbrains HTTP Client**, **Julia**, **k6**, **Kotlin**, **Lua**, **N4JS**, **Nim**, **Node.js/JavaScript** (ES5, ES6, AngularJS with Google Closure Compiler annotations, Flow types, Apollo GraphQL DataStore), **Objective-C**, **OCaml**, **Perl**, **PHP**, **PowerShell**, **Python**, **R**, **Ruby**, **Rust** (hyper, reqwest, rust-server), **Scala** (akka, http4s, scalaz, sttp, swagger-async-httpclient, pekko), **Swift** (2.x, 3.x, 4.x, 5.x), **Typescript** (AngularJS, Angular (9.x - 17.x), Aurelia, Axios, Fetch, Inversify, jQuery, Nestjs, Node, redux-query, Rxjs), **XoJo**, **Zapier** | -| **Server stubs** | **Ada**, **C#** (ASP.NET Core, Azure Functions), **C++** (Pistache, Restbed, Qt5 QHTTPEngine), **Erlang**, **F#** (Giraffe), **Go** (net/http, Gin, Echo), **Haskell** (Servant, Yesod), **Java** (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, Jersey, RestEasy, Play Framework, [PKMST](https://github.com/ProKarma-Inc/pkmst-getting-started-examples), [Vert.x](https://vertx.io/), [Apache Camel](https://camel.apache.org/), [Helidon](https://helidon.io/)), **Julia**, **Kotlin** (Spring Boot, [Ktor](https://github.com/ktorio/ktor), [Vert.x](https://vertx.io/)), **PHP** ([Flight](https://docs.flightphp.com/), Laravel, Lumen, [Mezzio (fka Zend Expressive)](https://github.com/mezzio/mezzio), Slim, Silex, [Symfony](https://symfony.com/)), **Python** (FastAPI, Flask), **NodeJS**, **Ruby** (Sinatra, Rails5), **Rust** ([rust-server](https://openapi-generator.tech/docs/generators/rust-server/)), **Scala** (Akka, [Finch](https://github.com/finagle/finch), [Lagom](https://github.com/lagom/lagom), [Play](https://www.playframework.com/), [Cask](https://github.com/com-lihaoyi/cask), Scalatra) | -| **API documentation generators** | **HTML**, **Confluence Wiki**, **Asciidoc**, **Markdown**, **PlantUML** | -| **Configuration files** | [**Apache2**](https://httpd.apache.org/) | -| **Others** | **GraphQL**, **JMeter**, **Ktorm**, **MySQL Schema**, **Postman Collection**, **Protocol Buffer**, **WSDL** | - -## Table of contents - - - [OpenAPI Generator](#openapi-generator) - - [Overview](#overview) - - [Table of Contents](#table-of-contents) - - [1 - Installation](#1---installation) - - [1.1 - Compatibility](#11---compatibility) - - [1.2 - Artifacts on Maven Central](#12---artifacts-on-maven-central) - - [1.3 - Download JAR](#13---download-jar) - - [1.4 - Build Projects](#14---build-projects) - - [1.5 - Homebrew](#15---homebrew) - - [1.6 - Docker](#16---docker) - - [1.7 - NPM](#17---npm) - - [2 - Getting Started](#2---getting-started) - - [3 - Usage](#3---usage) - - [3.1 - Customization](#31---customization) - - [3.2 - Workflow Integration](#32---workflow-integration-maven-gradle-github-cicd) - - [3.3 - Online Generators](#33---online-openapi-generator) - - [3.4 - License Information on Generated Code](#34---license-information-on-generated-code) - - [3.5 - IDE Integration](#35---ide-integration) - - [4 - Companies/Projects using OpenAPI Generator](#4---companiesprojects-using-openapi-generator) - - [5 - Presentations/Videos/Tutorials/Books](#5---presentationsvideostutorialsbooks) - - [6 - About Us](#6---about-us) - - [6.1 - OpenAPI Generator Core Team](#61---openapi-generator-core-team) - - [6.2 - OpenAPI Generator Technical Committee](#62---openapi-generator-technical-committee) - - [6.3 - History of OpenAPI Generator](#63---history-of-openapi-generator) - - [7 - License](#7---license) - -## [1 - Installation](#table-of-contents) - -### [1.1 - Compatibility](#table-of-contents) - -The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The openapi-generator project has the following compatibilities with the OpenAPI Specification: - -| OpenAPI Generator Version | Release Date | Notes | -| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------- | -| 7.6.0 (upcoming minor release) [SNAPSHOT](https://oss.sonatype.org/content/repositories/snapshots/org/openapitools/openapi-generator-cli/7.6.0-SNAPSHOT/) | 17.54.2024 | Minor release with breaking changes (with fallback) | -| [7.5.0](https://github.com/OpenAPITools/openapi-generator/releases/tag/v7.5.0) (latest stable release) | 17.04.2024 | Minor release with breaking changes (with fallback) | -| [6.6.0](https://github.com/OpenAPITools/openapi-generator/releases/tag/v6.6.0) | 11.05.2023 | Minor release with breaking changes (with fallback) | -| [5.4.0](https://github.com/OpenAPITools/openapi-generator/releases/tag/v5.4.0) | 31.01.2022 | Minor release with breaking changes (with fallback) | -| [4.3.1](https://github.com/OpenAPITools/openapi-generator/releases/tag/v4.3.1) | 06.05.2020 | Patch release (enhancements, bug fixes, etc) | - -OpenAPI Spec compatibility: 1.0, 1.1, 1.2, 2.0, 3.0, 3.1 (beta support) - -(We do not publish daily/nightly build. Please use SNAPSHOT instead) - -For old releases, please refer to the [**Release**](https://github.com/OpenAPITools/openapi-generator/releases) page. - -For decomissioned generators/libraries/frameworks, please refer to [the "Decommission" label](https://github.com/OpenAPITools/openapi-generator/issues?q=label%3ADecommission+is%3Amerged+) in the pull request page. - -## [1.2 - Artifacts on Maven Central](#table-of-contents) +```shell +mvn clean install +``` -You can find our released artifacts on maven central: +To deploy it to a remote Maven repository instead, configure the settings of the repository and execute: -**Core:** -```xml - - org.openapitools - openapi-generator - ${openapi-generator-version} - +```shell +mvn clean deploy ``` -See the different versions of the [openapi-generator](https://search.maven.org/artifact/org.openapitools/openapi-generator) artifact available on maven central. -**Cli:** -```xml - - org.openapitools - openapi-generator-cli - ${openapi-generator-version} - -``` -See the different versions of the [openapi-generator-cli](https://search.maven.org/artifact/org.openapitools/openapi-generator-cli) artifact available on maven central. +Refer to the [OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for more information. -**Maven plugin:** -```xml - - org.openapitools - openapi-generator-maven-plugin - ${openapi-generator-version} - -``` -* See the different versions of the [openapi-generator-maven-plugin](https://search.maven.org/artifact/org.openapitools/openapi-generator-maven-plugin) artifact available on maven central. -* [Readme](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-maven-plugin/README.md) +### Maven users + +Add this dependency to your project's POM: -**Gradle plugin:** ```xml - org.openapitools - openapi-generator-gradle-plugin - ${openapi-generator-version} + org.openapitools + openapi-java-client + 1.0.0 + compile ``` -* See the different versions of the [openapi-generator-gradle-plugin](https://search.maven.org/artifact/org.openapitools/openapi-generator-gradle-plugin) artifact available on maven central. -* [Readme](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-gradle-plugin/README.adoc) - -### [1.3 - Download JAR](#table-of-contents) - -If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 11 runtime at a minimum): - -JAR location: `https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.5.0/openapi-generator-cli-7.5.0.jar` - -For **Mac/Linux** users: -```sh -wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.5.0/openapi-generator-cli-7.5.0.jar -O openapi-generator-cli.jar -``` - -For **Windows** users, you will need to install [wget](http://gnuwin32.sourceforge.net/packages/wget.htm) or you can use Invoke-WebRequest in PowerShell (3.0+), e.g. -``` -Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.5.0/openapi-generator-cli-7.5.0.jar -``` - -After downloading the JAR, run `java -jar openapi-generator-cli.jar help` to show the usage. - -For Mac users, please make sure Java 11 is installed (Tips: run `java -version` to check the version), and export `JAVA_HOME` in order to use the supported Java version: -```sh -export JAVA_HOME=`/usr/libexec/java_home -v 1.11` -export PATH=${JAVA_HOME}/bin:$PATH -``` - - -### Launcher Script - -One downside to manual jar downloads is that you don't keep up-to-date with the latest released version. We have a Bash launcher script at [bin/utils/openapi-generator.cli.sh](./bin/utils/openapi-generator-cli.sh) which resolves this issue. - -To install the launcher script, copy the contents of the script to a location on your path and make the script executable. - -An example of setting this up (NOTE: Always evaluate scripts curled from external systems before executing them). - -``` -mkdir -p ~/bin/openapitools -curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh > ~/bin/openapitools/openapi-generator-cli -chmod u+x ~/bin/openapitools/openapi-generator-cli -export PATH=$PATH:~/bin/openapitools/ -``` - -Now, `openapi-generator-cli` is "installed". On invocation, it will query the GitHub repository for the most recently released version. If this matches the last downloaded jar, -it will execute as normal. If a newer version is found, the script will download the latest release and execute it. - -If you need to invoke an older version of the generator, you can define the variable `OPENAPI_GENERATOR_VERSION` either ad hoc or globally. You can export this variable if you'd like to persist a specific release version. - -Examples: - -``` -# Execute latest released openapi-generator-cli -openapi-generator-cli version -# Execute version 4.1.0 for the current invocation, regardless of the latest released version -OPENAPI_GENERATOR_VERSION=4.1.0 openapi-generator-cli version +### Gradle users -# Execute version 4.1.0-SNAPSHOT for the current invocation -OPENAPI_GENERATOR_VERSION=4.1.0-SNAPSHOT openapi-generator-cli version +Add this dependency to your project's build file: -# Execute version 4.0.2 for every invocation in the current shell session -export OPENAPI_GENERATOR_VERSION=4.0.2 -openapi-generator-cli version # is 4.0.2 -openapi-generator-cli version # is also 4.0.2 +```groovy + repositories { + mavenCentral() // Needed if the 'openapi-java-client' jar has been published to maven central. + mavenLocal() // Needed if the 'openapi-java-client' jar has been published to the local maven repo. + } -# To "install" a specific version, set the variable in .bashrc/.bash_profile -echo "export OPENAPI_GENERATOR_VERSION=4.0.2" >> ~/.bashrc -source ~/.bashrc -openapi-generator-cli version # is always 4.0.2, unless any of the above overrides are done ad hoc + dependencies { + implementation "org.openapitools:openapi-java-client:1.0.0" + } ``` -### [1.4 - Build Projects](#table-of-contents) - -To build from source, you need the following installed and available in your `$PATH:` - -* [Java 11](https://adoptium.net/) - -* [Apache Maven 3.3.4 or greater](https://maven.apache.org/) (optional) - -After cloning the project, you can build it from source using [maven wrapper](https://maven.apache.org/wrapper/): - -- Linux: `./mvnw clean install` -- Windows: `mvnw.cmd clean install` +### Others -#### Nix users +At first generate the JAR by executing: -If you're a nix user, you can enter OpenAPI Generator shell, by typing: -```sh -nix develop +```shell +mvn clean package ``` -It will enter a shell with Java 11 installed. -Direnv supports automatically loading of the nix developer shell, so if you're using direnv too, type: -```sh -direnv allow -``` -and have `java` and `mvn` set up with correct versions each time you enter project directory. - -The default build contains minimal static analysis (via CheckStyle). To run your build with PMD and Spotbugs, use the `static-analysis` profile: +Then manually install the following JARs: -- Linux: `./mvnw -Pstatic-analysis clean install` -- Windows: `mvnw.cmd -Pstatic-analysis clean install` +* `target/openapi-java-client-1.0.0.jar` +* `target/lib/*.jar` -### [1.5 - Homebrew](#table-of-contents) +## Getting Started -To install, run `brew install openapi-generator` +Please follow the [installation](#installation) instruction and execute the following Java code: -Here is an example usage to generate a Ruby client: -```sh -openapi-generator generate -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -g ruby -o /tmp/test/ -``` +```java -To reinstall with the latest master, run `brew uninstall openapi-generator && brew install --HEAD openapi-generator` +// Import classes: +import org.openapitools.client.ApiClient; +import org.openapitools.client.ApiException; +import org.openapitools.client.Configuration; +import org.openapitools.client.auth.*; +import org.openapitools.client.models.*; +import org.openapitools.client.api.PetApi; -To install OpenJDK (pre-requisites), please run -```sh -brew tap AdoptOpenJDK/openjdk -brew install --cask adoptopenjdk11 -export JAVA_HOME=`/usr/libexec/java_home -v 1.11` -``` +public class Example { + public static void main(String[] args) { + ApiClient defaultClient = Configuration.getDefaultApiClient(); + defaultClient.setBasePath("http://petstore.swagger.io/v2"); + + // Configure OAuth2 access token for authorization: petstore_auth + OAuth petstore_auth = (OAuth) defaultClient.getAuthentication("petstore_auth"); + petstore_auth.setAccessToken("YOUR ACCESS TOKEN"); -or download installer via https://adoptium.net/ + PetApi apiInstance = new PetApi(defaultClient); + Pet pet = new Pet(); // Pet | Pet object that needs to be added to the store + try { + Pet result = apiInstance.addPet(pet); + System.out.println(result); + } catch (ApiException e) { + System.err.println("Exception when calling PetApi#addPet"); + System.err.println("Status code: " + e.getCode()); + System.err.println("Reason: " + e.getResponseBody()); + System.err.println("Response headers: " + e.getResponseHeaders()); + e.printStackTrace(); + } + } +} -To install Maven (optional), please run -```sh -brew install maven ``` -### [1.6 - Docker](#table-of-contents) - -#### Public Pre-built Docker images - - - [https://hub.docker.com/r/openapitools/openapi-generator-cli/](https://hub.docker.com/r/openapitools/openapi-generator-cli/) (official CLI) - - [https://hub.docker.com/r/openapitools/openapi-generator-online/](https://hub.docker.com/r/openapitools/openapi-generator-online/) (official web service) - - -#### OpenAPI Generator CLI Docker Image - -The OpenAPI Generator image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version. - -To generate code with this image, you'll need to mount a local location as a volume. - -Example: - -```sh -docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \ - -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \ - -g go \ - -o /local/out/go -``` - -The generated code will be located under `./out/go` in the current directory. - -#### OpenAPI Generator Online Docker Image - -The openapi-generator-online image can act as a self-hosted web application and API for generating code. This container can be incorporated into a CI pipeline, and requires at least two HTTP requests and some docker orchestration to access generated code. - -Example usage: - -```sh -# Start container at port 8888 and save the container id -> CID=$(docker run -d -p 8888:8080 openapitools/openapi-generator-online) - -# allow for startup -> sleep 10 - -# Get the IP of the running container (optional) -GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}' $CID) - -# Execute an HTTP request to generate a Ruby client -> curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \ --d '{"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"}' \ -'http://localhost:8888/api/gen/clients/ruby' - -{"code":"c2d483.3.4672-40e9-91df-b9ffd18d22b8","link":"http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8"} - -# Download the generated zip file -> wget http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8 - -# Unzip the file -> unzip c2d483.3.4672-40e9-91df-b9ffd18d22b8 - -# Shutdown the openapi generator image -> docker stop $CID && docker rm $CID -``` - -#### Development in docker - -You can use `run-in-docker.sh` to do all development. This script maps your local repository to `/gen` -in the docker container. It also maps `~/.m2/repository` to the appropriate container location. - -To execute `mvn package`: - -```sh -git clone https://github.com/openapitools/openapi-generator -cd openapi-generator -./run-in-docker.sh mvn package -``` - -Build artifacts are now accessible in your working directory. - -Once built, `run-in-docker.sh` will act as an executable for openapi-generator-cli. To generate code, you'll need to output to a directory under `/gen` (e.g. `/gen/out`). For example: - -```sh -./run-in-docker.sh help # Executes 'help' command for openapi-generator-cli -./run-in-docker.sh list # Executes 'list' command for openapi-generator-cli -./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml \ - -g go -o /gen/out/go-petstore -p packageName=petstore # generates go client, outputs locally to ./out/go-petstore -``` - -##### Troubleshooting - -If an error like this occurs, just execute the **./mvnw clean install -U** command: - -> org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test (default-test) on project openapi-generator: A type incompatibility occurred while executing org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test: java.lang.ExceptionInInitializerError cannot be cast to java.io.IOException - -```sh -./run-in-docker.sh ./mvnw clean install -U -``` - -> Failed to execute goal org.fortasoft:gradle-maven-plugin:1.0.8:invoke (default) on project openapi-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.BuildException: Could not execute build using Gradle distribution 'https://services.gradle.org/distributions/gradle-4.7-bin.zip' - -Right now: no solution for this one :| - -#### Run Docker in Vagrant -Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads). - ```sh -git clone https://github.com/openapitools/openapi-generator.git -cd openapi-generator -vagrant up -vagrant ssh -cd /vagrant -./run-in-docker.sh ./mvnw package -``` - -### [1.7 - NPM](#table-of-contents) - -There is also an [NPM package wrapper](https://www.npmjs.com/package/@openapitools/openapi-generator-cli) available for different platforms (e.g. Linux, Mac, Windows). (JVM is still required) -Please see the [project's README](https://github.com/openapitools/openapi-generator-cli) there for more information. - -Install it globally to get the CLI available on the command line: - -```sh -npm install @openapitools/openapi-generator-cli -g -openapi-generator-cli version -``` - - -To use a specific version of "openapi-generator-cli" - -```sh -openapi-generator-cli version-manager set 7.0.1 -``` - -Or install it as dev-dependency: - -```sh -npm install @openapitools/openapi-generator-cli -D -``` - -## [2 - Getting Started](#table-of-contents) - -To generate a PHP client for [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml), please run the following -```sh -git clone https://github.com/openapitools/openapi-generator -cd openapi-generator -./mvnw clean package -java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \ - -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \ - -g php \ - -o /var/tmp/php_api_client -``` -(if you're on Windows, replace the last command with `java -jar modules\openapi-generator-cli\target\openapi-generator-cli.jar generate -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -g php -o c:\temp\php_api_client`) - - -You can also download the JAR (latest release) directly from [maven.org](https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.0.1/openapi-generator-cli-7.0.1.jar) - - -To get a list of **general** options available, please run `java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar help generate` - -To get a list of PHP specified options (which can be passed to the generator with a config file via the `-c` option), please run `java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar config-help -g php` - -## [3 - Usage](#table-of-contents) - -### To generate a sample client library -You can build a client against the [Petstore API](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml) as follows: - -```sh -./bin/generate-samples.sh ./bin/configs/java-okhttp-gson.yaml -``` - -(On Windows, please install [GIT Bash for Windows](https://gitforwindows.org/) to run the command above) - -This script uses the default library, which is `okhttp-gson`. It will run the generator with this command: - -```sh -java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \ - -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \ - -g java \ - -t modules/openapi-generator/src/main/resources/Java \ - --additional-properties artifactId=petstore-okhttp-gson,hideGenerationTimestamp=true \ - -o samples/client/petstore/java/okhttp-gson -``` - -with a number of options. [The java options are documented here.](docs/generators/java.md) - -You can also get the options with the `help generate` command (below only shows partial results): - -``` -NAME - openapi-generator-cli generate - Generate code with the specified - generator. - -SYNOPSIS - openapi-generator-cli generate - [(-a | --auth )] - [--api-name-suffix ] [--api-package ] - [--artifact-id ] [--artifact-version ] - [(-c | --config )] [--dry-run] - [(-e | --engine )] - [--enable-post-process-file] - [(-g | --generator-name )] - [--generate-alias-as-model] [--git-host ] - [--git-repo-id ] [--git-user-id ] - [--global-property ...] [--group-id ] - [--http-user-agent ] - [(-i | --input-spec )] - [--ignore-file-override ] - [--import-mappings ...] - [--instantiation-types ...] - [--invoker-package ] - [--language-specific-primitives ...] - [--legacy-discriminator-behavior] [--library ] - [--log-to-stderr] [--minimal-update] - [--model-name-prefix ] - [--model-name-suffix ] - [--model-package ] - [(-o | --output )] [(-p | --additional-properties )...] - [--package-name ] [--release-note ] - [--remove-operation-id-prefix] - [--reserved-words-mappings ...] - [(-s | --skip-overwrite)] [--server-variables ...] - [--skip-validate-spec] [--strict-spec ] - [(-t