swagger-api / swaggerhub-gradle-plugin

Gradle plugin for SwaggerHub

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

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

swaggerhub-gradle-plugin's Issues

Tests Fail

Following the OAS commit the tests fail.

Adding optional bath bases

Hello. Our company uses the on-premise solution for SwaggerHub. In addition to the host, we also have a "versioning" path segment. (i.e, https://swaggerhub.mgt.{compName}.com/v1/apis/...}. Looking at the source code for this plugin, it appears that we don't have the option of adding additional path segments on top of the host. Are there any plans to support this? Thanks!

Aos version is not recognized

Hey, when using the plugin, I looked at https://github.com/swagger-api/swaggerhub-gradle-plugin/pull/5/files.
the AOS version is not recognized as expected even though the JSON file starts {"openapi":"3.0.1",

swaggerhubUpload {
api 'xxx'
owner 'xxx'
version '1.0.0'
isPrivate true
inputFile "${project.rootDir}/build/docs/swagger.json"
token swggerhubToken
}

but when going into swaggerHub it suggests "Update Editor to OpenAPI 3.0?" (it is uploaded as version 2)

thanks!

Mark as default and published

I wanted to use the plugin to push our api schema to SwaggerHub. This is done automatically within a Jenkins build pipeline. In addition to pushing, I also want to mark the version as "published" and "default".

Via API calls I can achieve this with the following endpoints:

• https://app.swaggerhub.com/apis-docs/swagger-hub/registry-api/1.0.66#/APIs/setApiDefaultVersion
• https://app.swaggerhub.com/apis-docs/swagger-hub/registry-api/1.0.66#/APIs/setLifecycleSettings

Is it also possible to set these options within the plugin?

Thank you

swaggerhubUpload task doesn't download resolved yaml/json

I have written api spec on swaggerhub which refers some common domains defined within myorg. See example below.

components:
  headers:
    x-correlation-id:
      description: Unique correlation ID auto generated for server for each api call.
      required: true
      schema:
        $ref: 'https://api.swaggerhub.com/domains/myorg/CommonComponents/1.0.0#/components/schemas/x-correlation-id'    

When I download the api spec yaml using swaggerhubDownload gradle task, it doesn't resolve the reference. It just downloads it as is which is not in good to feed to next task in my workflow for codegen.

Suggestion
I looked up swaggerhub documentation and there is option to download resolved api spec by passing a query parameter resolved=true. Reference https://support.smartbear.com/swaggerhub/docs/apis/downloading-swagger-definition.html

I tried using this query param in postman and it works.

Can we add resolved as a parameter to the swaggerhubDownload task?

DownloadTask doesn't use the `/v1` suffix to form the URL

The documentation says that an API visible at http(s)://{swaggerhub-host}/apis/{owner}/{api}/{version} will be downloadable at http(s)://{swaggerhub-host}/v1/apis/{owner}/{api}/{version} —

In SwaggerHub On-Premise:
http(s)://{swaggerhub-host}/v1/apis/{owner}/{api}/{version}?resolved=true

But the DownloadTask gets me the output of an HTML, which is same as skipping the /v1 part in the URL.

Is this project still alive?

We currently evaluate integration of swagger hub into our gradle build.
The default examples fail with similar issues as in #10 with recent gradle versions.
According PR (#11 ) closed without comment.
Last commit 8 month ago.

Is this repo still maintained? If not, maybe add a hint in README?

Gradle plugin is not uploading

Hi Team,
Here the below plugin added in my build.gradle:

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

swaggerhubUpload {
api 'PetStoreAPI'
owner 'rajeshkommuri'
version '1.0.1-SNAPSHOT'
inputFile 'target/petStoreAPI.json'
token 'XXXXXXXX'

}

We ran this in JDK8 and JDK11,

JSON file is getting generated using java code.

It is not giving any error when we ran with gradle 6.X and not uploading anything as well.

It is giving the below error message when we ran with Gradle 7.0

A problem was found with the configuration of task ':swaggerhubUpload' (type 'UploadTask').

• Type 'UploadTask' property 'port' of type int shouldn't be annotated with @optional.

  Reason: Properties of primitive type cannot be optional.

  Possible solutions:

  1. Remove the @optional annotation.
  2. Use the java.lang.Integer type instead.

  Please refer to https://docs.gradle.org/7.0/userguide/validation_problems.html#cannot_use_optional_on_primitive_types for more details about this problem.

Please help us to resolve this issue as it is a critical issue for us.

Thanks in Advance.

Incompatible with gradle 7+

swaggerhub-gradle-plugin/src/main/java/io/swagger/swaggerhub/tasks/DownloadTask.java

Lines 83 to 87 in 2d32c37

	@Input
	@Optional
	public Integer getPort() {
	return port;
	}

These changes are not released in a new version of the gradle plugin, and therefore are incompatible with newer versions of gradle, complaining about field incorrectly marked as @Optional

Please release new version.