forked from loafle/openapi-generator-original
Improve "Getting Started" type docs
This commit is contained in:
Jim Schubert
parent
193b09693c
commit
185313e08e
76
docs/building.md
Normal file
76
docs/building.md
Normal file
@ -0,0 +1,76 @@
|
||||
---
|
||||
id: contribute-building
|
||||
title: Building the code
|
||||
---
|
||||
|
||||
## Using Maven
|
||||
|
||||
To build from source, you need the following installed and available in your `$PATH:`
|
||||
|
||||
* [Java 8](http://java.oracle.com)
|
||||
|
||||
* [Apache maven 3.3.4 or greater](http://maven.apache.org/)
|
||||
|
||||
After cloning the project, you can build it from source with this command:
|
||||
|
||||
```bash
|
||||
mvn clean install
|
||||
```
|
||||
|
||||
If you don't have maven installed, you may directly use the included [maven wrapper](https://github.com/takari/maven-wrapper), and build with the command:
|
||||
|
||||
```bash
|
||||
./mvnw clean install
|
||||
```
|
||||
|
||||
## Using 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`:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./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 /gen/bin/go-petstore.sh # Builds the Go client
|
||||
./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
|
||||
-g go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore
|
||||
```
|
||||
|
||||
### Docker in Vagrant
|
||||
|
||||
Prerequisite: install [Vagrant](https://www.vagrantup.com/downloads.html) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads).
|
||||
|
||||
```bash
|
||||
git clone http://github.com/openapitools/openapi-generator.git
|
||||
cd openapi-generator
|
||||
vagrant up
|
||||
vagrant ssh
|
||||
cd /vagrant
|
||||
./run-in-docker.sh mvn package
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If an error like this occurs, just execute the **mvn 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
|
||||
|
||||
```bash
|
||||
./run-in-docker.sh mvn 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 :|
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
id: code-of-conduct
|
||||
title: Contributor Covenant Code of Conduct
|
||||
title: Code of Conduct
|
||||
---
|
||||
|
||||
## Our Pledge
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
---
|
||||
id: contributing
|
||||
title: Guidelines For Contributing
|
||||
sidebar_label: Guidelines
|
||||
---
|
||||
|
||||
## Before submitting an issue
|
||||
|
||||
148
docs/installation.md
Normal file
148
docs/installation.md
Normal file
@ -0,0 +1,148 @@
|
||||
---
|
||||
id: installation
|
||||
title: CLI Installation
|
||||
---
|
||||
|
||||
There are a number of ways to use OpenAPI Generator. This page documents how to install the CLI artifact.
|
||||
Installing OpenAPI Generator's CLI tool allows users to generate all available generators from the command line.
|
||||
|
||||
Some of the following are cross-platform options and some are not, these are called out where possible.
|
||||
|
||||
## NPM
|
||||
|
||||
> **Platform(s)**: Linux, macOS, Windows
|
||||
|
||||
The [NPM package wrapper](https://github.com/openapitools/openapi-generator-cli) is cross-platform wrapper around the .jar artifact. It works by providing a CLI wrapper atop the JAR's command line options. This gives a simple interface layer which normalizes usage of the command line across operating systems, removing some differences in how options or switches are passed to the tool (depending on OS).
|
||||
**Install** the latest version of the tool globally, exposing the CLI on the command line:
|
||||
|
||||
```bash
|
||||
npm install @openapitools/openapi-generator-cli -g
|
||||
```
|
||||
|
||||
To install a specific version of the tool, pass the version during installation:
|
||||
|
||||
```bash
|
||||
npm install @openapitools/openapi-generator-cli@cli-3.3.4 -g
|
||||
```
|
||||
|
||||
To install the tool as a dev dependency in your current project:
|
||||
|
||||
```bash
|
||||
npm install @openapitools/openapi-generator-cli -D
|
||||
```
|
||||
Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc:
|
||||
|
||||
```bash
|
||||
npx openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/
|
||||
```
|
||||
|
||||
> `npx` will execute a globally available `openapi-generator`, and if not found it will fall back to project-local commands. The result is that the above command will work regardless of which installation method you've chosen.
|
||||
|
||||
## Homebrew
|
||||
|
||||
> **Platform(s)**: macOS
|
||||
|
||||
**Install** via [homebrew](https://brew.sh/):
|
||||
|
||||
```bash
|
||||
brew install openapi-generator
|
||||
```
|
||||
|
||||
Then, **generate** a ruby client from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc:
|
||||
|
||||
```bash
|
||||
openapi-generator generate -i petstore.yaml -g ruby -o /tmp/test/
|
||||
```
|
||||
|
||||
## Docker
|
||||
|
||||
> **Platform(s)**: Linux, macOS, Windows
|
||||
|
||||
The OpenAPI Generator Docker 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 from a valid [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml) doc with this image, you'll need to mount a local location as a volume.
|
||||
You'll then need to output the generated code to this mapped volume. Everything else works the same as if you ran the command on your host machine.
|
||||
|
||||
Here's an example generating a Go client:
|
||||
|
||||
```bash
|
||||
docker run --rm \
|
||||
-v ${PWD}:/local openapitools/openapi-generator-cli generate \
|
||||
-i petstore.yaml \
|
||||
-g go \
|
||||
-o /local/out/go
|
||||
```
|
||||
|
||||
## JAR
|
||||
|
||||
> **Platform(s)**: Linux, macOS, Windows
|
||||
|
||||
If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 8 runtime at a minimum):
|
||||
|
||||
JAR location: `http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/3.3.4/openapi-generator-cli-3.3.4.jar`
|
||||
|
||||
For **Mac/Linux** users:
|
||||
|
||||
```bash
|
||||
wget http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/3.3.4/openapi-generator-cli-3.3.4.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 http://central.maven.org/maven2/org/openapitools/openapi-generator-cli/3.3.4/openapi-generator-cli-3.3.4.jar
|
||||
```
|
||||
|
||||
After downloading the JAR, run `java -jar openapi-generator-cli.jar help` to show the usage.
|
||||
|
||||
For Mac users, please make sure Java 8 is installed (Tips: run `java -version` to check the version), and export `JAVA_HOME` in order to use the supported Java version:
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
|
||||
export PATH=${JAVA_HOME}/bin:$PATH
|
||||
```
|
||||
|
||||
## Bash Launcher Script
|
||||
|
||||
> **Platform(s)**: Linux, macOS, Windows (variable)
|
||||
|
||||
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](https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh) which solves this problem.
|
||||
|
||||
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).
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# Execute latest released openapi-generator-cli
|
||||
openapi-generator-cli version
|
||||
|
||||
# Execute version 3.1.0 for the current invocation, regardless of the latest released version
|
||||
OPENAPI_GENERATOR_VERSION=3.1.0 openapi-generator-cli version
|
||||
|
||||
# Execute version 3.1.0-SNAPSHOT for the current invocation
|
||||
OPENAPI_GENERATOR_VERSION=3.1.0-SNAPSHOT openapi-generator-cli version
|
||||
|
||||
# Execute version 3.0.2 for every invocation in the current shell session
|
||||
export OPENAPI_GENERATOR_VERSION=3.0.2
|
||||
openapi-generator-cli version # is 3.0.2
|
||||
openapi-generator-cli version # is also 3.0.2
|
||||
|
||||
# To "install" a specific version, set the variable in .bashrc/.bash_profile
|
||||
echo "export OPENAPI_GENERATOR_VERSION=3.0.2" >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
openapi-generator-cli version # is always 3.0.2, unless any of the above overrides are done ad hoc
|
||||
```
|
||||
@ -1,91 +0,0 @@
|
||||
---
|
||||
id: openapi-generator-online
|
||||
title: Online OpenAPI Generator
|
||||
---
|
||||
|
||||
One can also generate API clients or server stubs using the online openapi-generator.
|
||||
|
||||
Here are the public online services:
|
||||
|
||||
- latest stable version: http://api.openapi-generator.tech
|
||||
- latest master: http://api-latest-master.openapi-generator.tech (updated with latest master every hour)
|
||||
|
||||
The server is sponsored by [Linode](https://www.linode.com/) [](https://www.linode.com/)
|
||||
|
||||
(These services are beta and do not have any guarantee on service level)
|
||||
|
||||
If you prefer to run the service locally, here are the steps:
|
||||
```
|
||||
mvn clean install
|
||||
cd modules/openapi-generator-online
|
||||
mvn spring-boot:run
|
||||
```
|
||||
|
||||
:bulb: The online openapi-generator can be run via [Docker](https://github.com/OpenAPITools/openapi-generator#16---docker) as well.
|
||||
|
||||
For example, to generate Ruby API client, simply send the following HTTP request using curl:
|
||||
```sh
|
||||
curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' http://localhost:8080/api/gen/clients/ruby
|
||||
```
|
||||
Then you will receieve a JSON response with the URL to download the zipped code.
|
||||
|
||||
To customize the SDK, you can `POST` to `http://localhost:8080/gen/clients/{language}` with the following HTTP body:
|
||||
```json
|
||||
{
|
||||
"options": {},
|
||||
"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
|
||||
}
|
||||
```
|
||||
in which the `options` for a language can be obtained by submitting a `GET` request to `http://locahost:8080/api/gen/clients/{language}`:
|
||||
|
||||
For example, `curl http://localhost:8080/api/gen/clients/python` returns
|
||||
```json
|
||||
"packageName":{
|
||||
"opt":"packageName",
|
||||
"description":"python package name (convention: snake_case).",
|
||||
"type":"string",
|
||||
"default":"openapi_client"
|
||||
},
|
||||
"packageVersion":{
|
||||
"opt":"packageVersion",
|
||||
"description":"python package version.",
|
||||
"type":"string",
|
||||
"default":"1.0.0"
|
||||
},
|
||||
"sortParamsByRequiredFlag":{
|
||||
"opt":"sortParamsByRequiredFlag",
|
||||
"description":"Sort method arguments to place required parameters before optional parameters.",
|
||||
"type":"boolean",
|
||||
"default":"true"
|
||||
}
|
||||
|
||||
{}
|
||||
```
|
||||
To set package name to `pet_store`, the HTTP body of the request is as follows:
|
||||
```json
|
||||
{
|
||||
"options": {
|
||||
"packageName": "pet_store"
|
||||
},
|
||||
"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
|
||||
}
|
||||
```
|
||||
and here is the curl command:
|
||||
```sh
|
||||
curl -H "Content-type: application/json" -X POST -d '{"options": {"packageName": "pet_store"},"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' http://localhost:8080/api/gen/clients/python
|
||||
```
|
||||
|
||||
Instead of using `openAPIUrl` with an URL to the OpenAPI spec, one can include the spec in the JSON payload with `spec`, e.g.
|
||||
```json
|
||||
{
|
||||
"options": {},
|
||||
"spec": {
|
||||
"swagger": "2.0",
|
||||
"info": {
|
||||
"version": "1.0.0",
|
||||
"title": "Test API"
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
146
docs/online.md
Normal file
146
docs/online.md
Normal file
@ -0,0 +1,146 @@
|
||||
---
|
||||
id: online
|
||||
title: Online
|
||||
---
|
||||
|
||||
## Hosted
|
||||
|
||||
We offer online services, publicly and free of charge:
|
||||
|
||||
- latest stable version: http://api.openapi-generator.tech
|
||||
- latest master: http://api-latest-master.openapi-generator.tech (updated with latest master every hour)
|
||||
|
||||
> **Hosting Sponsor**
|
||||
> [](https://www.linode.com/)
|
||||
|
||||
These services are beta and do not have any guarantee on service level
|
||||
|
||||
Please refer to [Online OpenAPI Generator](./online-openapi-generator.md) on how to run and use the `openapi-generator-online` - a web service for `openapi-generator`.
|
||||
|
||||
## Docker Image
|
||||
|
||||
The openapi-generator-online Docker 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:
|
||||
|
||||
```bash
|
||||
# Start container at port 8888 and save the container id
|
||||
CID=$(docker run -d -p 8888:8080 \
|
||||
-e GENERATOR_HOST=http://localhost:8888 \
|
||||
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/2_0/petstore.yaml"}' \
|
||||
'http://localhost:8888/api/gen/clients/ruby'
|
||||
|
||||
# Example output:
|
||||
# {"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 (using "code" provided from your output)
|
||||
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}
|
||||
```
|
||||
|
||||
## Local/Self-hosting
|
||||
|
||||
If you prefer to run the service locally, here are the steps:
|
||||
|
||||
```bash
|
||||
mvn clean install
|
||||
cd modules/openapi-generator-online
|
||||
mvn spring-boot:run
|
||||
```
|
||||
|
||||
> The online openapi-generator can be run via [Docker](#docker-image) as well.
|
||||
|
||||
For example, to generate Ruby API client, simply send the following HTTP request using curl:
|
||||
|
||||
```bash
|
||||
curl -X POST -H "content-type:application/json" -d '{"openAPIUrl":"https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \
|
||||
http://localhost:8080/api/gen/clients/ruby
|
||||
```
|
||||
Then you will receive a JSON response with the URL to download the zipped code.
|
||||
|
||||
To customize the SDK, you can `POST` to `http://localhost:8080/gen/clients/{generator}` with the following HTTP body:
|
||||
|
||||
```json
|
||||
{
|
||||
"options": {},
|
||||
"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
|
||||
}
|
||||
```
|
||||
|
||||
Here, the `options` for a language can be obtained by submitting a `GET` request to `http://locahost:8080/api/gen/clients/{generator}`:
|
||||
|
||||
For example, `curl http://localhost:8080/api/gen/clients/python` returns
|
||||
|
||||
```json
|
||||
"packageName":{
|
||||
"opt":"packageName",
|
||||
"description":"python package name (convention: snake_case).",
|
||||
"type":"string",
|
||||
"default":"openapi_client"
|
||||
},
|
||||
"packageVersion":{
|
||||
"opt":"packageVersion",
|
||||
"description":"python package version.",
|
||||
"type":"string",
|
||||
"default":"1.0.0"
|
||||
},
|
||||
"sortParamsByRequiredFlag":{
|
||||
"opt":"sortParamsByRequiredFlag",
|
||||
"description":"Sort method arguments to place required parameters before optional parameters.",
|
||||
"type":"boolean",
|
||||
"default":"true"
|
||||
}
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
To set package name to `pet_store`, the HTTP body of the request is as follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"options": {
|
||||
"packageName": "pet_store"
|
||||
},
|
||||
"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"
|
||||
}
|
||||
```
|
||||
|
||||
and here is the curl command:
|
||||
```bash
|
||||
curl -H "Content-type: application/json" \
|
||||
-X POST \
|
||||
-d '{"options": {"packageName": "pet_store"},"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml"}' \
|
||||
http://localhost:8080/api/gen/clients/python
|
||||
```
|
||||
|
||||
Instead of using `openAPIUrl` with an URL to the OpenAPI spec, one can include the spec in the JSON payload with `spec`:
|
||||
|
||||
```json
|
||||
{
|
||||
"options": {},
|
||||
"spec": {
|
||||
"swagger": "2.0",
|
||||
"info": {
|
||||
"version": "1.0.0",
|
||||
"title": "Test API"
|
||||
},
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
99
docs/plugins.md
Normal file
99
docs/plugins.md
Normal file
@ -0,0 +1,99 @@
|
||||
---
|
||||
id: plugins
|
||||
title: Plugins
|
||||
---
|
||||
|
||||
## Maven
|
||||
|
||||
A Maven plugin to support the OpenAPI generator project
|
||||
|
||||
### Example
|
||||
|
||||
Add to your `build->plugins` section (default phase is `generate-sources` phase)
|
||||
|
||||
```xml
|
||||
<plugin>
|
||||
<groupId>org.openapitools</groupId>
|
||||
<artifactId>openapi-generator-maven-plugin</artifactId>
|
||||
<version>3.3.4</version>
|
||||
<executions>
|
||||
<execution>
|
||||
<goals>
|
||||
<goal>generate</goal>
|
||||
</goals>
|
||||
<configuration>
|
||||
<inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec>
|
||||
<generatorName>java</generatorName>
|
||||
<configOptions>
|
||||
<sourceFolder>src/gen/java/main</sourceFolder>
|
||||
</configOptions>
|
||||
</configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
</plugin>
|
||||
```
|
||||
|
||||
Followed by:
|
||||
|
||||
```bash
|
||||
mvn clean compile
|
||||
```
|
||||
|
||||
For full details of all options, see the [plugin README](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin).
|
||||
|
||||
## Gradle
|
||||
|
||||
This gradle plugin offers a declarative DSL via extensions (these are Gradle project extensions). These map almost fully 1:1 with the options you’d pass to the CLI or Maven plugin. The plugin maps the extensions to a task of the same name to provide a clean API. If you’re interested in the extension/task mapping concept from a high-level, you can check out [Gradle’s docs](https://docs.gradle.org/current/userguide/custom_plugins.html#sec:mapping_extension_properties_to_task_properties).
|
||||
|
||||
To include in your project, add the following to `build.gradle`:
|
||||
|
||||
```groovy
|
||||
buildscript {
|
||||
repositories {
|
||||
mavenLocal()
|
||||
mavenCentral()
|
||||
}
|
||||
dependencies {
|
||||
classpath "org.openapitools:openapi-generator-gradle-plugin:3.3.4"
|
||||
}
|
||||
}
|
||||
|
||||
apply plugin: 'org.openapi.generator'
|
||||
```
|
||||
|
||||
This gives access to the following tasks:
|
||||
|
||||
| Task | Description |
|
||||
| ---- | ----------- |
|
||||
| openApiGenerate | Generate code via Open API Tools Generator for Open API 2.0 or 3.x specification documents. |
|
||||
| openApiGenerators | Lists generators available via Open API Generators. |
|
||||
| openApiMeta | Generates a new generator to be consumed via Open API Generator. |
|
||||
| openApiValidate | Validates an Open API 2.0 or 3.x specification document. |
|
||||
|
||||
> The plugin implements the above tasks as project extensions of the same name. If you’d like to declare these tasks as dependencies to other tasks (using `dependsOn`), you’ll need a task reference. e.g.:
|
||||
> ```groovy
|
||||
> compileJava.dependsOn tasks.openApiGenerate
|
||||
> ```
|
||||
|
||||
For full details of all options, see the [plugin README](https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-gradle-plugin).
|
||||
|
||||
### Example
|
||||
|
||||
An example task for generating a kotlin client:
|
||||
|
||||
```groovy
|
||||
openApiGenerate {
|
||||
generatorName = "kotlin"
|
||||
inputSpec = "$rootDir/specs/petstore-v3.0.yaml".toString()
|
||||
outputDir = "$buildDir/generated".toString()
|
||||
apiPackage = "org.openapi.example.api"
|
||||
invokerPackage = "org.openapi.example.invoker"
|
||||
modelPackage = "org.openapi.example.model"
|
||||
modelFilesConstrainedTo = [
|
||||
"Error"
|
||||
]
|
||||
configOptions = [
|
||||
dateLibrary: "java8"
|
||||
]
|
||||
}
|
||||
```
|
||||
475
docs/usage.md
Normal file
475
docs/usage.md
Normal file
@ -0,0 +1,475 @@
|
||||
---
|
||||
id: usage
|
||||
title: Usage
|
||||
---
|
||||
|
||||
Options for OpenAPI Generator are the same whether you're using the CLI, Maven/Gradle Plugins, or Online generation options.
|
||||
This page demonstrates navigating the options via CLI. Commands are presented here in a logical progression as a tutorial, but you're welcome to skip directly to the [generate](#generate) command.
|
||||
|
||||
## help
|
||||
|
||||
The `help` option lists all commands available to the CLI.
|
||||
|
||||
```bash
|
||||
openapi-generator help
|
||||
usage: openapi-generator-cli <command> [<args>]
|
||||
|
||||
The most commonly used openapi-generator-cli commands are:
|
||||
config-help Config help for chosen lang
|
||||
generate Generate code with the specified generator.
|
||||
help Display help information
|
||||
list Lists the available generators
|
||||
meta MetaGenerator. Generator for creating a new template set and configuration for Codegen. The output will be based on the language you specify, and includes default templates to include.
|
||||
validate Validate specification
|
||||
version Show version information
|
||||
|
||||
See 'openapi-generator-cli help <command>' for more information on a specific
|
||||
command.
|
||||
|
||||
```
|
||||
|
||||
## list
|
||||
|
||||
The `list` command outputs a formatted list of every available generator. Pass the `-s/--short` option if you would like a CSV output for easy parsing.
|
||||
|
||||
```bash
|
||||
openapi-generator help list
|
||||
NAME
|
||||
openapi-generator-cli list - Lists the available generators
|
||||
|
||||
SYNOPSIS
|
||||
openapi-generator-cli list [(-s | --short)]
|
||||
|
||||
OPTIONS
|
||||
-s, --short
|
||||
shortened output (suitable for scripting)
|
||||
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
openapi-generator list -s | tr ',' '\n'
|
||||
```
|
||||
|
||||
For the full list of generators, refer to the [Generators List](./generators.md).
|
||||
|
||||
## config-help
|
||||
|
||||
The `config-help` option provides details about
|
||||
|
||||
```bash
|
||||
openapi-generator help config-help
|
||||
NAME
|
||||
openapi-generator-cli config-help - Config help for chosen lang
|
||||
|
||||
SYNOPSIS
|
||||
openapi-generator-cli config-help
|
||||
[(-f <output format> | --format <output format>)]
|
||||
[(-g <generator name> | --generator-name <generator name>)]
|
||||
[--markdown-header] [--named-header]
|
||||
[(-o <output location> | --output <output location>)]
|
||||
|
||||
OPTIONS
|
||||
-f <output format>, --format <output format>
|
||||
Write output files in the desired format. Options are 'text' and
|
||||
'markdown'. Default is 'text'.
|
||||
|
||||
-g <generator name>, --generator-name <generator name>
|
||||
generator to get config help for
|
||||
|
||||
--markdown-header
|
||||
When format=markdown, include this option to write out markdown
|
||||
headers (e.g. for docusaurus).
|
||||
|
||||
--named-header
|
||||
Header includes the generator name, for clarity in output
|
||||
|
||||
-o <output location>, --output <output location>
|
||||
Optionally write help to this location, otherwise default is
|
||||
standard output
|
||||
|
||||
```
|
||||
|
||||
The option of note is `-g/--generator-name` (other options are exposed for tooling).
|
||||
|
||||
You may pass any generator name (see [list](#list) command) to `-g`, and options specific to that generator will be displayed. Some generators have _many_ options, while others may have only a few.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
openapi-generator config-help -g go
|
||||
```
|
||||
|
||||
Outputs:
|
||||
|
||||
```text
|
||||
CONFIG OPTIONS
|
||||
packageName
|
||||
Go package name (convention: lowercase). (Default: openapi)
|
||||
|
||||
hideGenerationTimestamp
|
||||
Hides the generation timestamp when files are generated. (Default: true)
|
||||
|
||||
packageVersion
|
||||
Go package version. (Default: 1.0.0)
|
||||
|
||||
withGoCodegenComment
|
||||
whether to include Go codegen comment to disable Go Lint and collapse by default GitHub in PRs and diffs (Default: false)
|
||||
|
||||
withXml
|
||||
whether to include support for application/xml content type and include XML annotations in the model (works with libraries that provide support for JSON and XML) (Default: false)
|
||||
|
||||
prependFormOrBodyParameters
|
||||
Add form or body parameters to the beginning of the parameter list. (Default: false)
|
||||
```
|
||||
|
||||
To pass these go client generator-specific options to the `generate` command for a go client, use the `--additional-properties` option. See the [generate](#generate) command section for an example.
|
||||
|
||||
## meta
|
||||
|
||||
The `meta` command creates a new Java class and template files, used for creating your own custom templates.
|
||||
|
||||
```bash
|
||||
openapi-generator help meta
|
||||
NAME
|
||||
openapi-generator-cli meta - MetaGenerator. Generator for creating a new
|
||||
template set and configuration for Codegen. The output will be based on
|
||||
the language you specify, and includes default templates to include.
|
||||
|
||||
SYNOPSIS
|
||||
openapi-generator-cli meta [(-n <name> | --name <name>)]
|
||||
[(-o <output directory> | --output <output directory>)]
|
||||
[(-p <package> | --package <package>)] [(-t <type> | --type <type>)]
|
||||
|
||||
OPTIONS
|
||||
-n <name>, --name <name>
|
||||
the human-readable name of the generator
|
||||
|
||||
-o <output directory>, --output <output directory>
|
||||
where to write the generated files (current dir by default)
|
||||
|
||||
-p <package>, --package <package>
|
||||
the package to put the main class into (defaults to
|
||||
org.openapitools.codegen)
|
||||
|
||||
-t <type>, --type <type>
|
||||
the type of generator that is created
|
||||
```
|
||||
|
||||
For an in-depth example of using the `meta` command, see [Customization](./customization.md).
|
||||
|
||||
## validate
|
||||
|
||||
The `validate` command allows you to validate an input specification, optionally providing recommendations for error fixes or other improvements (if available).
|
||||
|
||||
```bash
|
||||
openapi-generator help validate
|
||||
NAME
|
||||
openapi-generator-cli validate - Validate specification
|
||||
|
||||
SYNOPSIS
|
||||
openapi-generator-cli validate
|
||||
(-i <spec file> | --input-spec <spec file>) [--recommend]
|
||||
|
||||
OPTIONS
|
||||
-i <spec file>, --input-spec <spec file>
|
||||
location of the OpenAPI spec, as URL or file (required)
|
||||
|
||||
--recommend
|
||||
|
||||
```
|
||||
|
||||
Valid Spec Example (using [petstore-v3.0.yaml](https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator-gradle-plugin/samples/local-spec/petstore-v3.0.yaml))
|
||||
```bash
|
||||
openapi-generator validate -i petstore-v3.0.yaml
|
||||
```
|
||||
```text
|
||||
Validating spec (petstore-v3.0.yaml)
|
||||
No validation issues detected.
|
||||
```
|
||||
|
||||
Invalid Spec Example (using [petstore-v3.0-invalid.yaml](https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator-gradle-plugin/samples/local-spec/petstore-v3.0-invalid.yaml)):
|
||||
|
||||
```bash
|
||||
openapi-generator validate -i petstore-v3.0-invalid.yaml
|
||||
```
|
||||
```text
|
||||
Validating spec (petstore-v3.0-invalid.yaml)
|
||||
Errors:
|
||||
-attribute info is missing
|
||||
|
||||
[error] Spec has 1 errors.
|
||||
```
|
||||
|
||||
## completion
|
||||
|
||||
Although not documented in the `help` output, the CLI offers a `completion` command, which can be used for auto-completion.
|
||||
|
||||
This command takes one or more parameters representing the args list you would otherwise pass to `openapi-generator`. For example:
|
||||
|
||||
```bash
|
||||
openapi-generator completion config-help
|
||||
--named-header
|
||||
-o
|
||||
--output
|
||||
-g
|
||||
--generator-name
|
||||
-l
|
||||
--lang
|
||||
```
|
||||
|
||||
An example bash completion script can be found in the repo at [scripts/openapi-generator-cli-completion.bash](https://github.com/OpenAPITools/openapi-generator/blob/master/scripts/openapi-generator-cli-completion.bash).
|
||||
|
||||
## generate
|
||||
|
||||
The `generate` command is the workhorse of the generator toolset. As such, it has _many_ more options and the previous commands. The options are abbreviated below, but you may expand the full descriptions.
|
||||
|
||||
|
||||
```bash
|
||||
openapi-generator help generate
|
||||
NAME
|
||||
openapi-generator-cli generate - Generate code with the specified
|
||||
generator.
|
||||
|
||||
SYNOPSIS
|
||||
openapi-generator-cli generate
|
||||
[(-a <authorization> | --auth <authorization>)]
|
||||
[--additional-properties <additional properties>...]
|
||||
[--api-package <api package>] [--artifact-id <artifact id>]
|
||||
[--artifact-version <artifact version>]
|
||||
[(-c <configuration file> | --config <configuration file>)]
|
||||
[-D <system properties>...] [--enable-post-process-file]
|
||||
[(-g <generator name> | --generator-name <generator name>)]
|
||||
[--git-repo-id <git repo id>] [--git-user-id <git user id>]
|
||||
[--group-id <group id>] [--http-user-agent <http user agent>]
|
||||
(-i <spec file> | --input-spec <spec file>)
|
||||
[--ignore-file-override <ignore file override location>]
|
||||
[--import-mappings <import mappings>...]
|
||||
[--instantiation-types <instantiation types>...]
|
||||
[--invoker-package <invoker package>]
|
||||
[--language-specific-primitives <language specific primitives>...]
|
||||
[--library <library>] [--log-to-stderr]
|
||||
[--model-name-prefix <model name prefix>]
|
||||
[--model-name-suffix <model name suffix>]
|
||||
[--model-package <model package>]
|
||||
[(-o <output directory> | --output <output directory>)]
|
||||
[--release-note <release note>] [--remove-operation-id-prefix]
|
||||
[--reserved-words-mappings <reserved word mappings>...]
|
||||
[(-s | --skip-overwrite)] [--skip-validate-spec]
|
||||
[(-t <template directory> | --template-dir <template directory>)]
|
||||
[--type-mappings <type mappings>...] [(-v | --verbose)]
|
||||
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>generate OPTIONS</summary>
|
||||
|
||||
```bash
|
||||
OPTIONS
|
||||
-a <authorization>, --auth <authorization>
|
||||
adds authorization headers when fetching the OpenAPI definitions
|
||||
remotely. Pass in a URL-encoded string of name:header with a comma
|
||||
separating multiple values
|
||||
|
||||
--additional-properties <additional properties>
|
||||
sets additional properties that can be referenced by the mustache
|
||||
templates in the format of name=value,name=value. You can also have
|
||||
multiple occurrences of this option.
|
||||
|
||||
--api-package <api package>
|
||||
package for generated api classes
|
||||
|
||||
--artifact-id <artifact id>
|
||||
artifactId in generated pom.xml
|
||||
|
||||
--artifact-version <artifact version>
|
||||
artifact version in generated pom.xml
|
||||
|
||||
-c <configuration file>, --config <configuration file>
|
||||
Path to json configuration file. File content should be in a json
|
||||
format {"optionKey":"optionValue", "optionKey1":"optionValue1"...}
|
||||
Supported options can be different for each language. Run
|
||||
config-help -g {generator name} command for language specific config
|
||||
options.
|
||||
|
||||
-D <system properties>
|
||||
sets specified system properties in the format of
|
||||
name=value,name=value (or multiple options, each with name=value)
|
||||
|
||||
--enable-post-process-file
|
||||
enablePostProcessFile
|
||||
|
||||
-g <generator name>, --generator-name <generator name>
|
||||
generator to use (see langs command for list)
|
||||
|
||||
--git-repo-id <git repo id>
|
||||
Git repo ID, e.g. openapi-generator.
|
||||
|
||||
--git-user-id <git user id>
|
||||
Git user ID, e.g. openapitools.
|
||||
|
||||
--group-id <group id>
|
||||
groupId in generated pom.xml
|
||||
|
||||
--http-user-agent <http user agent>
|
||||
HTTP user agent, e.g. codegen_csharp_api_client, default to
|
||||
'OpenAPI-Generator/{packageVersion}}/{language}'
|
||||
|
||||
-i <spec file>, --input-spec <spec file>
|
||||
location of the OpenAPI spec, as URL or file (required)
|
||||
|
||||
--ignore-file-override <ignore file override location>
|
||||
Specifies an override location for the .openapi-generator-ignore
|
||||
file. Most useful on initial generation.
|
||||
|
||||
--import-mappings <import mappings>
|
||||
specifies mappings between a given class and the import that should
|
||||
be used for that class in the format of type=import,type=import. You
|
||||
can also have multiple occurrences of this option.
|
||||
|
||||
--instantiation-types <instantiation types>
|
||||
sets instantiation type mappings in the format of
|
||||
type=instantiatedType,type=instantiatedType.For example (in Java):
|
||||
array=ArrayList,map=HashMap. In other words array types will get
|
||||
instantiated as ArrayList in generated code. You can also have
|
||||
multiple occurrences of this option.
|
||||
|
||||
--invoker-package <invoker package>
|
||||
root package for generated code
|
||||
|
||||
--language-specific-primitives <language specific primitives>
|
||||
specifies additional language specific primitive types in the format
|
||||
of type1,type2,type3,type3. For example:
|
||||
String,boolean,Boolean,Double. You can also have multiple
|
||||
occurrences of this option.
|
||||
|
||||
--library <library>
|
||||
library template (sub-template)
|
||||
|
||||
--log-to-stderr
|
||||
write all log messages (not just errors) to STDOUT. Useful for
|
||||
piping the JSON output of debug options (e.g. `-DdebugOperations`)
|
||||
to an external parser directly while testing a generator.
|
||||
|
||||
--model-name-prefix <model name prefix>
|
||||
Prefix that will be prepended to all model names. Default is the
|
||||
empty string.
|
||||
|
||||
--model-name-suffix <model name suffix>
|
||||
Suffix that will be appended to all model names. Default is the
|
||||
empty string.
|
||||
|
||||
--model-package <model package>
|
||||
package for generated models
|
||||
|
||||
-o <output directory>, --output <output directory>
|
||||
where to write the generated files (current dir by default)
|
||||
|
||||
--release-note <release note>
|
||||
Release note, default to 'Minor update'.
|
||||
|
||||
--remove-operation-id-prefix
|
||||
Remove prefix of operationId, e.g. config_getId => getId
|
||||
|
||||
--reserved-words-mappings <reserved word mappings>
|
||||
specifies how a reserved name should be escaped to. Otherwise, the
|
||||
default _<name> is used. For example id=identifier. You can also
|
||||
have multiple occurrences of this option.
|
||||
|
||||
-s, --skip-overwrite
|
||||
specifies if the existing files should be overwritten during the
|
||||
generation.
|
||||
|
||||
--skip-validate-spec
|
||||
Skips the default behavior of validating an input specification.
|
||||
|
||||
-t <template directory>, --template-dir <template directory>
|
||||
folder containing the template files
|
||||
|
||||
--type-mappings <type mappings>
|
||||
sets mappings between OpenAPI spec types and generated code types in
|
||||
the format of OpenaAPIType=generatedType,OpenAPIType=generatedType.
|
||||
For example: array=List,map=Map,string=String. You can also have
|
||||
multiple occurrences of this option.
|
||||
|
||||
-v, --verbose
|
||||
verbose mode
|
||||
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
At a minimum, `generate` requires:
|
||||
|
||||
* `-g` to specify the generator
|
||||
* `-o` to specify a meaningful output directory (defaults to the current directory!)
|
||||
* `-i` to specify the input OpenAPI document
|
||||
|
||||
### Examples
|
||||
|
||||
The following examples use [petstore.yaml](https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml).
|
||||
|
||||
#### Additional Properties
|
||||
|
||||
Generator-specific options should be passed as `--additional-properties`:
|
||||
|
||||
```bash
|
||||
openapi-generator generate -g go --additional-properties=prependFormOrBodyParameters=true \
|
||||
-o out -i petstore.yaml
|
||||
```
|
||||
|
||||
To pass more than one generator property, these can be combined via comma:
|
||||
|
||||
```bash
|
||||
--additional-properties=key1=value1,key2=value2
|
||||
```
|
||||
|
||||
#### Type Mappings and Import Mappings
|
||||
|
||||
Most generators allow for types bound to the OpenAPI Specification's types to be remapped to a user's desired types. Not _all_ type mappings can be reassigned, as some generators define mappings which are tightly coupled to the built-in templates.
|
||||
|
||||
If you're not using your own templates with star/glob package imports, you will most likely need to combine `--type-mappings` and `--import-mappings` together.
|
||||
|
||||
* `--type-mappings` Defines the user's target type
|
||||
* `--import-mappings` Informs the template of the type to be imported
|
||||
|
||||
Here's how one might change the `kotlin-spring` server generator's default of `OffsetDateTime` to `LocalDateTime`:
|
||||
|
||||
```bash
|
||||
openapi-generator generate \
|
||||
-i petstore.yaml \
|
||||
-g kotlin-spring \
|
||||
-o out \
|
||||
--additional-properties=library=spring-boot,beanValidations=true,swaggerAnnotations=true,serviceImplementation=true \
|
||||
--import-mappings=DateTime=java.time.LocalDateTime \
|
||||
--type-mappings=DateTime=java.time.LocalDateTime
|
||||
```
|
||||
|
||||
<!-- TODO: Document all primitive types here -->
|
||||
|
||||
> NOTE: mappings are applied to `DateTime`, as this is the representation of the primitive type. See [DefaultCodegen](https://github.com/OpenAPITools/openapi-generator/blob/7cee999543fcc00b7c1eb9f70f0456b707c7f9e2/modules/openapi-generator/src/main/java/org/openapitools/codegen/DefaultCodegen.java#L1431).
|
||||
|
||||
#### Configuration File
|
||||
|
||||
Rather than passing generator options in a CSV of `--additional-properties`, you may also provide the settings via JSON file.
|
||||
|
||||
For example, one of our typescript samples has the following configuration file:
|
||||
|
||||
```json
|
||||
{
|
||||
"npmName": "@swagger/typescript-fetch-petstore",
|
||||
"npmVersion": "1.0.0",
|
||||
"npmRepository" : "https://skimdb.npmjs.com/registry",
|
||||
"snapshot" : false,
|
||||
"supportsES6": true
|
||||
}
|
||||
```
|
||||
|
||||
These settings can be passed via `-c filename`. Here, we've saved the above as `config.json`:
|
||||
|
||||
```bash
|
||||
openapi-generator generate -i petstore.yaml -g typescript-fetch -o out \
|
||||
-c config.json
|
||||
```
|
||||
@ -50,7 +50,6 @@ public class OpenAPIGenerator {
|
||||
ListGenerators.class,
|
||||
Generate.class,
|
||||
Meta.class,
|
||||
Langs.class,
|
||||
Help.class,
|
||||
ConfigHelp.class,
|
||||
Validate.class,
|
||||
|
||||
@ -1,41 +0,0 @@
|
||||
/*
|
||||
* Copyright 2018 OpenAPI-Generator Contributors (https://openapi-generator.tech)
|
||||
* Copyright 2018 SmartBear Software
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
package org.openapitools.codegen.cmd;
|
||||
|
||||
import ch.lambdaj.collection.LambdaIterable;
|
||||
import io.airlift.airline.Command;
|
||||
import org.openapitools.codegen.CodegenConfig;
|
||||
|
||||
import java.util.Locale;
|
||||
|
||||
import static ch.lambdaj.Lambda.on;
|
||||
import static ch.lambdaj.collection.LambdaCollections.with;
|
||||
import static java.util.ServiceLoader.load;
|
||||
|
||||
/**
|
||||
* User: lanwen Date: 24.03.15 Time: 20:25
|
||||
*/
|
||||
@Command(name = "langs", description = "Shows available languages (deprecated. use 'list' instead)")
|
||||
public class Langs implements Runnable {
|
||||
@Override
|
||||
public void run() {
|
||||
LambdaIterable<String> langs =
|
||||
with(load(CodegenConfig.class)).extract(on(CodegenConfig.class).getName());
|
||||
System.out.printf(Locale.ROOT, "Available languages (generators): %s%n", langs);
|
||||
}
|
||||
}
|
||||
@ -22,7 +22,7 @@ public class ListGenerators implements Runnable {
|
||||
@Option(name = {"-s", "--short" }, description = "shortened output (suitable for scripting)")
|
||||
private Boolean shortened = false;
|
||||
|
||||
@Option(name = {"-d", "--docsite" }, description = "format for docusaurus site output")
|
||||
@Option(name = {"-d", "--docsite" }, description = "format for docusaurus site output", hidden = true)
|
||||
private Boolean docusaurus = false;
|
||||
|
||||
@Override
|
||||
|
||||
@ -1,193 +1,106 @@
|
||||
This website was created with [Docusaurus](https://docusaurus.io/).
|
||||
# Go API client for openapi
|
||||
|
||||
# What's In This Document
|
||||
This is a sample server Petstore server. For this sample, you can use the api key `special-key` to test the authorization filters.
|
||||
|
||||
* [Get Started in 5 Minutes](#get-started-in-5-minutes)
|
||||
* [Directory Structure](#directory-structure)
|
||||
* [Editing Content](#editing-content)
|
||||
* [Adding Content](#adding-content)
|
||||
* [Full Documentation](#full-documentation)
|
||||
## Overview
|
||||
This API client was generated by the [OpenAPI Generator](https://openapi-generator.tech) project. By using the [OpenAPI-spec](https://www.openapis.org/) from a remote server, you can easily generate an API client.
|
||||
|
||||
# Get Started in 5 Minutes
|
||||
- API version: 1.0.0
|
||||
- Package version: 1.0.0
|
||||
- Build package: org.openapitools.codegen.languages.GoClientCodegen
|
||||
|
||||
1. Make sure all the dependencies for the website are installed:
|
||||
## Installation
|
||||
|
||||
```sh
|
||||
# Install dependencies
|
||||
$ yarn
|
||||
Install the following dependencies:
|
||||
```
|
||||
2. Run your dev server:
|
||||
|
||||
```sh
|
||||
# Start the site
|
||||
$ yarn start
|
||||
go get github.com/stretchr/testify/assert
|
||||
go get golang.org/x/oauth2
|
||||
go get golang.org/x/net/context
|
||||
go get github.com/antihax/optional
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Your project file structure should look something like this
|
||||
|
||||
```
|
||||
my-docusaurus/
|
||||
docs/
|
||||
doc-1.md
|
||||
doc-2.md
|
||||
doc-3.md
|
||||
website/
|
||||
blog/
|
||||
2016-3-11-oldest-post.md
|
||||
2017-10-24-newest-post.md
|
||||
core/
|
||||
node_modules/
|
||||
pages/
|
||||
static/
|
||||
css/
|
||||
img/
|
||||
package.json
|
||||
sidebar.json
|
||||
siteConfig.js
|
||||
Put the package under your project folder and add the following in import:
|
||||
```golang
|
||||
import "./openapi"
|
||||
```
|
||||
|
||||
# Editing Content
|
||||
## Documentation for API Endpoints
|
||||
|
||||
## Editing an existing docs page
|
||||
All URIs are relative to *http://petstore.swagger.io/v2*
|
||||
|
||||
Edit docs by navigating to `docs/` and editing the corresponding document:
|
||||
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
|
||||
|
||||
`docs/doc-to-be-edited.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: page-needs-edit
|
||||
title: This Doc Needs To Be Edited
|
||||
---
|
||||
## Documentation For Models
|
||||
|
||||
Edit me...
|
||||
- [ApiResponse](docs/ApiResponse.md)
|
||||
- [Category](docs/Category.md)
|
||||
- [Order](docs/Order.md)
|
||||
- [Pet](docs/Pet.md)
|
||||
- [Tag](docs/Tag.md)
|
||||
- [User](docs/User.md)
|
||||
|
||||
|
||||
## Documentation For Authorization
|
||||
|
||||
## api_key
|
||||
- **Type**: API key
|
||||
|
||||
Example
|
||||
```golang
|
||||
auth := context.WithValue(context.Background(), sw.ContextAPIKey, sw.APIKey{
|
||||
Key: "APIKEY",
|
||||
Prefix: "Bearer", // Omit if not necessary.
|
||||
})
|
||||
r, err := client.Service.Operation(auth, args)
|
||||
```
|
||||
## 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
|
||||
|
||||
Example
|
||||
```golang
|
||||
auth := context.WithValue(context.Background(), sw.ContextAccessToken, "ACCESSTOKENSTRING")
|
||||
r, err := client.Service.Operation(auth, args)
|
||||
```
|
||||
|
||||
For more information about docs, click [here](https://docusaurus.io/docs/en/navigation)
|
||||
Or via OAuth2 module to automatically refresh tokens and perform user authentication.
|
||||
```golang
|
||||
import "golang.org/x/oauth2"
|
||||
|
||||
## Editing an existing blog post
|
||||
/* Perform OAuth2 round trip request and obtain a token */
|
||||
|
||||
Edit blog posts by navigating to `website/blog` and editing the corresponding post:
|
||||
|
||||
`website/blog/post-to-be-edited.md`
|
||||
```markdown
|
||||
---
|
||||
id: post-needs-edit
|
||||
title: This Blog Post Needs To Be Edited
|
||||
---
|
||||
|
||||
Edit me...
|
||||
tokenSource := oauth2cfg.TokenSource(createContext(httpClient), &token)
|
||||
auth := context.WithValue(oauth2.NoContext, sw.ContextOAuth2, tokenSource)
|
||||
r, err := client.Service.Operation(auth, args)
|
||||
```
|
||||
|
||||
For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog)
|
||||
## Author
|
||||
|
||||
# Adding Content
|
||||
|
||||
## Adding a new docs page to an existing sidebar
|
||||
|
||||
1. Create the doc as a new markdown file in `/docs`, example `docs/newly-created-doc.md`:
|
||||
|
||||
```md
|
||||
---
|
||||
id: newly-created-doc
|
||||
title: This Doc Needs To Be Edited
|
||||
---
|
||||
|
||||
My new content here..
|
||||
```
|
||||
|
||||
1. Refer to that doc's ID in an existing sidebar in `website/sidebar.json`:
|
||||
|
||||
```javascript
|
||||
// Add newly-created-doc to the Getting Started category of docs
|
||||
{
|
||||
"docs": {
|
||||
"Getting Started": [
|
||||
"quick-start",
|
||||
"newly-created-doc" // new doc here
|
||||
],
|
||||
...
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
For more information about adding new docs, click [here](https://docusaurus.io/docs/en/navigation)
|
||||
|
||||
## Adding a new blog post
|
||||
|
||||
1. Make sure there is a header link to your blog in `website/siteConfig.js`:
|
||||
|
||||
`website/siteConfig.js`
|
||||
```javascript
|
||||
headerLinks: [
|
||||
...
|
||||
{ blog: true, label: 'Blog' },
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
2. Create the blog post with the format `YYYY-MM-DD-My-Blog-Post-Title.md` in `website/blog`:
|
||||
|
||||
`website/blog/2018-05-21-New-Blog-Post.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
author: Frank Li
|
||||
authorURL: https://twitter.com/foobarbaz
|
||||
authorFBID: 503283835
|
||||
title: New Blog Post
|
||||
---
|
||||
|
||||
Lorem Ipsum...
|
||||
```
|
||||
|
||||
For more information about blog posts, click [here](https://docusaurus.io/docs/en/adding-blog)
|
||||
|
||||
## Adding items to your site's top navigation bar
|
||||
|
||||
1. Add links to docs, custom pages or external links by editing the headerLinks field of `website/siteConfig.js`:
|
||||
|
||||
`website/siteConfig.js`
|
||||
```javascript
|
||||
{
|
||||
headerLinks: [
|
||||
...
|
||||
/* you can add docs */
|
||||
{ doc: 'my-examples', label: 'Examples' },
|
||||
/* you can add custom pages */
|
||||
{ page: 'help', label: 'Help' },
|
||||
/* you can add external links */
|
||||
{ href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
|
||||
...
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
For more information about the navigation bar, click [here](https://docusaurus.io/docs/en/navigation)
|
||||
|
||||
## Adding custom pages
|
||||
|
||||
1. Docusaurus uses React components to build pages. The components are saved as .js files in `website/pages/en`:
|
||||
1. If you want your page to show up in your navigation header, you will need to update `website/siteConfig.js` to add to the `headerLinks` element:
|
||||
|
||||
`website/siteConfig.js`
|
||||
```javascript
|
||||
{
|
||||
headerLinks: [
|
||||
...
|
||||
{ page: 'my-new-custom-page', label: 'My New Custom Page' },
|
||||
...
|
||||
],
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
For more information about custom pages, click [here](https://docusaurus.io/docs/en/custom-pages).
|
||||
|
||||
# Full Documentation
|
||||
|
||||
Full documentation can be found on the [website](https://docusaurus.io/).
|
||||
|
||||
@ -9,11 +9,15 @@
|
||||
"title": "Release Notes: 3.0.0",
|
||||
"sidebar_label": "Release Notes: 3.0.0"
|
||||
},
|
||||
"contribute-building": {
|
||||
"title": "Building the code"
|
||||
},
|
||||
"code-of-conduct": {
|
||||
"title": "Contributor Covenant Code of Conduct"
|
||||
"title": "Code of Conduct"
|
||||
},
|
||||
"contributing": {
|
||||
"title": "Guidelines For Contributing"
|
||||
"title": "Guidelines For Contributing",
|
||||
"sidebar_label": "Guidelines"
|
||||
},
|
||||
"core-team": {
|
||||
"title": "Core Team Members"
|
||||
@ -339,6 +343,9 @@
|
||||
"generators/typescript-node": {
|
||||
"title": "generators/typescript-node"
|
||||
},
|
||||
"installation": {
|
||||
"title": "CLI Installation"
|
||||
},
|
||||
"integrations": {
|
||||
"title": "Workflow Integrations"
|
||||
},
|
||||
@ -348,22 +355,34 @@
|
||||
"openapi-generator-online": {
|
||||
"title": "Online OpenAPI Generator"
|
||||
},
|
||||
"online": {
|
||||
"title": "Online"
|
||||
},
|
||||
"plugins": {
|
||||
"title": "Plugins"
|
||||
},
|
||||
"fork-qna": {
|
||||
"title": "Swagger Codegen Fork: Q&A"
|
||||
},
|
||||
"roadmap": {
|
||||
"title": "Roadmap"
|
||||
},
|
||||
"usage": {
|
||||
"title": "Usage"
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"Roadmap": "Roadmap",
|
||||
"Get Started": "Get Started",
|
||||
"Generators": "Generators",
|
||||
"Roadmap": "Roadmap",
|
||||
"Team": "Team",
|
||||
"Blog": "Blog"
|
||||
},
|
||||
"categories": {
|
||||
"Getting Started": "Getting Started",
|
||||
"Extending": "Extending",
|
||||
"Contributing": "Contributing",
|
||||
"About": "About",
|
||||
"Process Documentation": "Process Documentation",
|
||||
"Releases": "Releases",
|
||||
"API": "API",
|
||||
"First Category": "First Category"
|
||||
|
||||
@ -74,6 +74,7 @@ class HomeSplash extends React.Component {
|
||||
<Logo img_src={`${baseUrl}img/color-logo.svg`} />
|
||||
<PromoSection>
|
||||
<Button href="#try">Try It Out</Button>
|
||||
<Button href={docUrl('installation.html')}>Install</Button>
|
||||
<Button href={docUrl('generators.html')}>Generators</Button>
|
||||
<Button href={docUrl('customization.html')}>Customization</Button>
|
||||
<Button href={docUrl('integrations.html')}>Integrations</Button>
|
||||
@ -160,7 +161,7 @@ class Index extends React.Component {
|
||||
| -i petstore.yaml \\
|
||||
| -g go \\
|
||||
| -o /local/out/go
|
||||
|
|
||||
| \`\`\`
|
||||
`;
|
||||
const TryOutDocker = () => (
|
||||
<Block id="tryDocker">
|
||||
|
||||
@ -1,5 +1,20 @@
|
||||
{
|
||||
"docs": {
|
||||
"Getting Started": [
|
||||
"installation",
|
||||
"plugins",
|
||||
"online",
|
||||
"usage"
|
||||
],
|
||||
"Extending": [
|
||||
"customization",
|
||||
"integrations"
|
||||
],
|
||||
"Contributing": [
|
||||
"contributing",
|
||||
"code-of-conduct",
|
||||
"contribute-building"
|
||||
],
|
||||
"About": [
|
||||
"roadmap",
|
||||
"faq",
|
||||
@ -7,33 +22,6 @@
|
||||
"fork-qna"
|
||||
],
|
||||
|
||||
"Process Documentation": [
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "Contributing",
|
||||
"ids": [
|
||||
"contributing",
|
||||
"code-of-conduct"
|
||||
]
|
||||
},
|
||||
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "Extending",
|
||||
"ids": [
|
||||
"customization",
|
||||
"integrations"
|
||||
]
|
||||
},
|
||||
|
||||
{
|
||||
"type": "subcategory",
|
||||
"label": "Documentation",
|
||||
"ids": [
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"Releases": [
|
||||
"release-3-0-0"
|
||||
],
|
||||
|
||||
@ -154,8 +154,9 @@ const siteConfig = {
|
||||
|
||||
// For no header links in the top nav bar -> headerLinks: [],
|
||||
headerLinks: [
|
||||
{doc: 'roadmap', label: 'Roadmap'},
|
||||
{doc: 'installation', label: 'Get Started'},
|
||||
{doc: 'generators', label: 'Generators'},
|
||||
{doc: 'roadmap', label: 'Roadmap'},
|
||||
// {doc: 'doc4', label: 'API'},
|
||||
{ page: "team", label: "Team" },
|
||||
// {page: 'help', label: 'Help'},
|
||||
@ -221,7 +222,6 @@ const siteConfig = {
|
||||
repoUrl: 'https://https://github.com/OpenAPITools/openapi-generator',
|
||||
|
||||
team: team,
|
||||
|
||||
};
|
||||
|
||||
module.exports = siteConfig;
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user