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

• 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 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

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

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