Build Status

swaggerhub-gradle-plugin

A simple gradle plugin to integrate SwaggerHub hosting of OpenAPI/Swagger definitions with a gradle build process, using the SwaggerHub API.

Features

The pattern of usage is likely to depend on whether a code first or design first approach is followed.

Example use cases

Code First

  1. Code API implementation.
  2. Automatically generate API definition from implementation, e.g. via swagger-core annotations and swagger gradle plugin. See also swagger-core wiki
  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 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.

Installation

Gradle 2.1 and higher

plugins {
  id "io.swagger.swaggerhub" version "1.0.1"
}

Gradle 1.x and 2.0

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.io.swagger:swaggerhub:1.0.1"
  }
}

apply plugin: "io.swagger.swaggerhub"

Tasks

swaggerhubDownload

Example Usage

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

swaggerhubUpload

Example Usage

swaggerhubUpload {
    api 'PetStoreAPI'
    owner 'jsfrench'
    version '1.0.1-SNAPSHOT'
    inputFile 'target/petStoreAPI.json'
    token  'duMmyAPiKEy'
}

Example Usage together with swagger-gradle-plugin (code first)


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 'jsfrench'
    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