Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/SmartBear/swaggerhub-gradle-plugin
Gradle plugin for SwaggerHub
https://github.com/SmartBear/swaggerhub-gradle-plugin
gradle on-prem saas swaggerhub
Last synced: 3 days ago
JSON representation
Gradle plugin for SwaggerHub
- Host: GitHub
- URL: https://github.com/SmartBear/swaggerhub-gradle-plugin
- Owner: SmartBear
- License: apache-2.0
- Created: 2018-06-22T09:59:59.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-01-10T08:07:09.000Z (10 months ago)
- Last Synced: 2024-11-09T03:48:22.035Z (8 days ago)
- Topics: gradle, on-prem, saas, swaggerhub
- Language: Java
- Homepage:
- Size: 266 KB
- Stars: 19
- Watchers: 9
- Forks: 19
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://jenkins.swagger.io/view/OSS%20-%20Java/job/oss-swaggerhub-gradle-plugin)
# swaggerhub-gradle-plugin 
A simple gradle plugin to integrate [SwaggerHub](https:\\swaggerhub.com) hosting of [OpenAPI/Swagger](https://swagger.io/specification/) definitions with a gradle build process, using the [SwaggerHub API](https://app.swaggerhub.com/apis/swagger-hub/registry-api).
## Features
* Download/upload API definitions from/to SwaggerHub.
* Supports `json` and `yaml` format 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](https://swaggerhub.com/blog/api-design/design-first-or-code-first-api-development/) approach is followed.
## Example use cases
### Code First
1. Code API implementation.
2. Automatically generate API definition from implementation, e.g. via [swagger-core](https://github.com/swagger-api/swagger-core) [annotations](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations) and [swagger gradle plugin](https://github.com/swagger-api/swagger-core/tree/master/modules/swagger-gradle-plugin). See also [swagger-core wiki](https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started)
3. Upload generated API definition to SwaggerHub with swaggerhub-gradle-plugin.
### Design First
1. Write API definition (e.g. in Swagger Editor or SwaggerHub).
2. Download API definition with swaggerhub-gradle-plugin.
3. Pass API definition to another Swagger tool e.g.
- [swagger-codegen](https://github.com/swagger-api/swagger-codegen) to generate API client and resource classes.
- [swagger-inflector](https://github.com/swagger-api/swagger-inflector) to automatically wire up the API definition to the implementation and provide out-of-the-box mocking.
## Installation
```
plugins {
id "io.swagger.swaggerhub" version "1.1.0"
}
```
## Tasks
### swaggerhubDownload
#### Example Usage
* Download a public API definition in json format from SwaggerHub and save to a local file.
```
swaggerhubDownload {
api 'PetStoreAPI'
owner 'swagger-hub'
version '1.0.0'
outputFile 'target/test/petStoreAPI.json'
}
```
#### 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`
**`oas`** | Version of the OpenApi Specification the definition adheres to | false | `2.0`
**`resolved`** | Download a resolved version of the API definition | false | `false`
**`onPremise`** | Uses the API path suffix for on-premise SwaggerHub deployments | false | `false`
**`onPremiseAPISuffix`** | Custom API Suffix path for any future changes in SwaggerHub API pattern for on-premise deployments | false | `/v1`
***
### swaggerhubUpload
#### Example Usage
* Upload an API definition in json format as a public API in SwaggerHub.
```
swaggerhubUpload {
api 'PetStoreAPI'
owner 'swagger-hub'
version '1.0.1-SNAPSHOT'
inputFile 'target/petStoreAPI.json'
token 'duMmyAPiKEy'
}
```
#### Example Usage together with `swagger-gradle-plugin` (code first)
* Upload an API definition in json format (resolved via `swagger-gradle-plugin`) as a public API in SwaggerHub.
```
plugins {
...
id 'java'
id "io.swagger.core.v3.swagger-gradle-plugin" version '2.0.6'
id "io.swagger.swaggerhub" version "1.0.1"
}
...
resolve {
outputFileName = 'PetStoreAPI'
outputFormat = 'JSON'
prettyPrint = 'TRUE'
classpath = sourceSets.main.runtimeClasspath
resourcePackages = ['test.petstore']
outputPath = 'target'
}
swaggerhubUpload {
dependsOn resolve
api 'PetStoreAPI'
owner 'swagger-hub'
version '1.0.1-SNAPSHOT'
inputFile 'target/petStoreAPI.json'
token 'duMmyAPiKEy'
}
```
#### 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`
**`onPremise`** | Uses the API path suffix for on-premise SwaggerHub deployments | false | `false`
**`onPremiseAPISuffix`** | Custom API Suffix path for any future changes in SwaggerHub API pattern for on-premise deployments | false | `/v1`