swaggerhub-maven-plugin
A simple maven plugin to access SwaggerHub hosting of OpenAPI/Swagger definitions with a maven build process, using the SwaggerHub API.
Features
- Download/upload API definitions from/to SwaggerHub.
- Supports
jsonandyamlformat for API definitions. - Authenticate with API key for restricted operations (e.g downloading a private API definition).
- Connects to SwaggerHub cloud by default or local SwaggerHub instance through optional configuration.
The pattern of usage is likely to depend on whether a code first or design first approach is followed.
Example use cases
Code First
- Code API implementation.
- Automatically generate API definition from implementation, e.g. via swagger-core annotations and swagger maven plugin. See also swagger-core wiki
- Upload generated API definition to SwaggerHub with swaggerhub-maven-plugin.
Design First
- Write API definition (e.g. in Swagger Editor or SwaggerHub).
- Download API definition with swaggerhub-maven-plugin.
- Pass API definition to another Swagger tool e.g.
- swagger-codegen-maven-plugin to generate API client and resource classes.
- swagger-inflector to automatically wire up the API definition to the implementation and provide out-of-the-box mocking.
Goals
download
Example Usage
- Download a public API definition in json format from SwaggerHub automatically as part of the default maven build lifecycle and save to a local file.
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swaggerhub-maven-plugin</artifactId>
<version>1.0.2</version>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>download</goal>
</goals>
<configuration>
<api>PetStoreAPI</api>
<owner>jsfrench</owner>
<version>1.0.0</version>
<outputFile>target/petStoreAPI.json</outputFile>
</configuration>
</execution>
</executions>
</plugin>Parameters
| Parameter | Description | Required | Default |
|---|---|---|---|
api |
API name | true | - |
owner |
API owner | true | - |
version |
API version | true | - |
outputFile |
API definition is written to this file | true | - |
token |
SwaggerHub API key, required to access private definitions | false | - |
format |
API definition format, json or yaml |
false | json |
host |
URL of SwaggerHub API | false | api.swaggerhub.com |
protocol |
Protocol for SwaggerHub API,http or https |
false | https |
port |
Port to access SwaggerHub API | false | 443 |
upload
Example Usage
- Upload an API definition in json format as a public API in SwaggerHub.
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swaggerhub-maven-plugin</artifactId>
<version>1.0.2</version>
<executions>
<execution>
<phase>deploy</phase>
<goals>
<goal>upload</goal>
</goals>
<configuration>
<api>PetStoreAPI</api>
<owner>jsfrench</owner>
<version>1.0.1-SNAPSHOT</version>
<inputFile>target/petStoreAPI.json</inputFile>
<token>${SWAGGERHUB_APIKEY}</token>
</configuration>
</execution>
</executions>
</plugin>Example Usage together with swagger-maven-plugin (code first)
<plugin>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>2.0.5</version>
<configuration>
<outputFileName>petStoreAPI</outputFileName>
<outputPath>${project.build.directory}</outputPath>
<outputFormat>JSON</outputFormat>
<resourcePackages>
<package>test.petstore</package>
</resourcePackages>
<prettyPrint>TRUE</prettyPrint>
</configuration>
<executions>
<execution>
<phase>compile</phase>
<goals>
<goal>resolve</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>io.swagger</groupId>
<artifactId>swaggerhub-maven-plugin</artifactId>
<version>1.0.2</version>
<executions>
<execution>
<phase>deploy</phase>
<goals>
<goal>upload</goal>
</goals>
<configuration>
<api>PetStoreAPI</api>
<owner>jsfrench</owner>
<version>1.0.1-SNAPSHOT</version>
<inputFile>target/petStoreAPI.json</inputFile>
<token>${SWAGGERHUB_APIKEY}</token>
</configuration>
</execution>
</executions>
</plugin>Parameters
| Parameter | Description | Required | Default |
|---|---|---|---|
api |
API name | true | - |
owner |
API owner | true | - |
version |
API version | true | - |
inputFile |
Local file containing the API definition in json or yaml format | true | - |
token |
SwaggerHub API key | true | - |
format |
API definition format, json or yaml |
false | json |
isPrivate |
Defines whether the API should be private on SwaggerHub (using true requires a paid plan) |
false | false |
host |
URL of SwaggerHub API | false | api.swaggerhub.com |
protocol |
Protocol for SwaggerHub API,http or https |
false | https |
port |
Port to access SwaggerHub API | false | 443 |
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent