swagger-api / swaggerhub-maven-plugin Goto Github PK

A simple maven plugin to access SwaggerHub hosting of OpenAPI/Swagger from a maven build process.

License: Apache License 2.0

Java 100.00%

swaggerhub maven on-prem saas

swaggerhub-maven-plugin's Introduction

swaggerhub-maven-plugin

A simple Maven plugin to access SwaggerHub hosting of OpenAPI/Swagger definitions within a Maven build process, using the SwaggerHub API.

Features

Download/upload API and domain definitions from/to SwaggerHub.
Upload multiple API or domains at once.
Authenticate with an API key for restricted operations (for example, to download private definitions).
Automatically provision an SCM integration to update source control with changes made to definitions.
Supports YAML and JSON format for definitions.
Connects to SwaggerHub SaaS by default, with an optional configuration to point to a local SwaggerHub On-Premise instance.

SwaggerHub On-Premise users need v. 1.20.0 to provision SCM integrations via SwaggerHub Maven plugin.

Example use cases
- Code-first
- Design-first
Dependencies
- Stable version
- Snapshots
Goals
- download
  - Parameters
- upload

Example use cases

The usage pattern depends on whether you use the code-first or design-first approach.

Code-first

Code your API implementation.
Automatically generate the API definition from the source code, for example, using Swagger Core annotations and Swagger Maven plugin. See the Swagger Core wiki to learn more.
Upload the generated API definition to SwaggerHub using the SwaggerHub Maven plugin.

Design-first

Write your API definition on SwaggerHub.
Download the API definition using the SwaggerHub Maven plugin.
Pass the API definition to another Swagger tool, for example:
- Use Swagger Codegen Maven plugin to generate API server and client code.
- Use Swagger Inflector to automatically wire up the API definition to the implementation and provide out-of-the-box mocking.

Dependencies

Stable version

  <dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swaggerhub-maven-plugin</artifactId>
    <version>1.0.10</version>
  </dependency>

Snapshots

Snapshots are available from the Sonatype Nexus Snapshots repository. To use a snapshot version, add the following to the <repositories> section of your pom.xml:

<repository>
	<id>sonatype-snapshots</id>
	<name>Sonatype Snapshots</name>
	<url>https://oss.sonatype.org/content/repositories/snapshots</url>
	<snapshots>
		<enabled>true</enabled>
	</snapshots>
</repository>

Goals

SwaggerHub Maven plugin provides two goals, download and upload.

download

This goal downloads an API or domain definition from SwaggerHub to a local file as part of the default Maven build lifecycle.

    <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swaggerhub-maven-plugin</artifactId>
        <version>1.0.10</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 or domain name (case-sensitive)	yes	-
`owner`	Owner name (case-sensitive)	yes	-
`version`	API or domain version (case-sensitive)	yes	-
`outputFile`	The definition will be saved to this file	yes	-
`token`	SwaggerHub API key, required to access private definitions	no	-
`definitionType`	Definition type, `API` or `domain`	no	`API`
`format`	File format to download, `json` or `yaml`	no	`json`
`host`	SwaggerHub hostname. Use `api.swaggerhub.com` for SwaggerHub SaaS.	no	`api.swaggerhub.com`
`protocol`	SwaggerHub server protocol, `http` or `https`	no	`https`
`port`	SwaggerHub server port, typically 80 for `http` and 443 for `https`	no	443
`basepath`	Base path prefix for SwaggerHub Registry API calls. Leave blank for SwaggerHub SaaS, use `v1` for SwaggerHub On-Premise.	no	-

upload

This goal creates or updates one or more API or domain definitions on SwaggerHub. All definitions are saved in the owner account (organization or user), and the token owner must have permissions to create and update definitions in this account.

Additionally, there is the option of provisioning a SwaggerHub SCM integration which will allow changes made in SwaggerHub to be pushed back to source control.

There are two uploadType modes:

inputFile - Upload a single API or domain definition.
directory - Upload one or more definitions from the specified definitionDirectory, optionally filtered by a regular expression. All definitions must be of the same type - either all APIs or all domains.

Parameters

Common parameters:

Parameter	Description	Required?	Default
`uploadType`	Possible values: `inputFile` - upload a single API or domain; `directory` - upload multiple definitions stored in a directory	yes	-
`owner`	The account name (case-sensitive) to upload the definitions to	yes	-
`token`	SwaggerHub API key. The API key owner must have permissions to create and update definitions in the `owner` account	yes	-
`definitionType`	Definition type, `API` or `domain`	no	`API`
`isPrivate`	Specifies whether the uploaded definitions will be made public (`false`) or private (`true`)	no	`false`
`skipFailures`	Specifies whether a build should fail when errors are encountered	no	false
`host`	SwaggerHub hostname. Use `api.swaggerhub.com` for SwaggerHub SaaS.	no	`api.swaggerhub.com`
`protocol`	SwaggerHub server protocol, `http` or `https`	no	`https`
`port`	SwaggerHub server port, typically 80 for `http` and 443 for `https`	no	443
`basepath`	Base path prefix for SwaggerHub Registry API calls. Leave blank for SwaggerHub SaaS, use `v1` for SwaggerHub On-Premise.	no	-

Additional parameters for uploadType=inputFile:

Parameter	Description	Required?	Default
`api`	The name of the API or domain to create or update (case-sensitive)	yes	-
`version`	Version to create or update (case-sensitive). If this version already exists, it must not be published.	yes	-
`inputFile`	Local file containing the API or domain definition in the JSON or YAML format	yes	-
`format`	Definition format, `json` or `yaml`	no	`json`

Additional parameters for uploadType=directory:

Parameter	Description	Required?	Default
`definitionDirectory`	Directory containing the definitions to be uploaded to SwaggerHub. Note that subdirectories are not included in the upload.	yes	-
`definitionFileNameRegex`	Regular expression that specifies the files to be uploaded. This regex matches against file names without extensions. If not specified, all .json, .yaml and .yml files from the `definitionDirectory` will be uploaded.	no	-

Additional parameters for SCM integration provisioning:

Parameter	Description	Required?	SCM Specific?	Default
`scmProvider`	SCM to create a SwaggerHub Integration for.	yes	-	-
`scmToken`	User generated API token to be used for SCM requests	no	`GITHUB`	-
`scmPersonalAccessToken`	Similar to the above	no	`AZURE_DEVOPS_SERVICES`	-
`scmUsername`	The account-name (case-sensitive) with which to authenticate	no	`BITBUCKET`	-
`scmPassword`	The password to be used in conjunction with the above `scmUsername`	no	`BITBUCKET`	-
`repository`	The repository to push SwaggerHub changes to	yes	-	-
`repositoryOwner`	The SCM account which owns the above repository	no	`GITHUB`. `BITBUCKET`	-
`scmProject`	Team Project which contains the target repository	no	`AZURE_DEVOPS_SERVICES`	-
`scmOrganization`	Specific to Azure DevOps Services, the organization with which to synchronize	no	`AZURE_DEVOPS_SERVICES`	-
`scmUrl`	Host URL of the SCM	no	`AZURE_DEVOPS_SERVER`	-
`scmHost`	Similar to the above	no	`GITLAB`	-
`scmProjectCollection`	Project collection which contains the target repositories project	no	`AZURE_DEVOPS_SERVER`	DefaultCollection
`enableScmIntegration`	Specifies whether to enable the SCM integration. If enabled, SwaggerHub changes will be pushed automatically on save	no	-	true
`branch`	The repository branch to push SwaggerHub changes to	no	-	SWAGGERHUB

Multi-upload considerations

When using uploadType=directory, all definitions to be uploaded must be stored in the definitionDirectory (the directory itself, not subdirectories). The definitionType parameter specifies whether the files will be uploaded as APIs (default) or domains.

The plugin only processes files with the following extensions: .yaml, .yml, .json. Files with other extensions are ignored. The files must be valid JSON or YAML files.

By default, the plugin uploads all JSON and YAML files from the specified directory, but you can use definitionFileNameRegex to narrow down the files to be uploaded. The regular expression matches against file names without file extensions. The matching is partial unless the regex contains the ^ (beginning of line) and $ (end of line) anchors. To make the matching case-insensitive, include (?i) at the beginning, or (?iu) for Unicode-aware case-insensitive matching. Examples:

acme matches file names that contain "acme" in lower case.
^acme matches file names that begin with "acme" in lower case.
^(?i)acme matches file names that begin with "acme" in any letter case.

API/domain names and versions are generated by parsing the info section of the definitions. The info section must include non-empty title and version keys.

Names are generated based on the info.title, with characters other than A-Za-z0-9_ replaced with underscores. For example, a definition with title: Sample API will be saved under the name Sample_API on SwaggerHub.
Versions are extracted from the info.version key. If this version already exists in SwaggerHub, it will be updated with the new definition (unless the version is published - in this case the update will be rejected).

If an error occurs while uploading any definition, the build will fail and subsequent definitions will not be uploaded.

SCM integration provisioning considerations

Supported SCM's include: GITHUB, BITBUCKET, AZURE_DEVOPS_SERVICES, AZURE_DEVOPS_SERVER, GITLAB
SwaggerHub On-Premise supports this method of SCM integration provisioning since v. 1.20.0.
Care should be taken when specifying SCM parameters. Validation does not take place prior to making the request to SwaggerHub and issues can arise due to incorrectly configured integrations
Use only the parameters that are required for the SCM of your choice. For example BITBUCKET relies on scmUsername and scmPassword; if an scmToken is also included, the Bitbucket integration will attempt to authenticate with the token. This is not possible and will cause integration errors.
BITBUCKET can use app passwords to authenticate. App passwords are substitute passwords for a user account which you can use for scripts and integrating tools to avoid putting your real password into configuration files. App password permissions required are:
- Account : Email, Read
- Repositories : Read, Write
Documentation on how to generate an app password can be found here.
AZURE_DEVOPS_SERVICES and AZURE_DEVOPS_SERVER use personal access tokens which will eventually expire. In the event of token expiring, the integration will need to be deleted and recreated (either manually or via the plugin).

See Microsoft documentation here for details on creating a Personal Access Token. Please ensure that the token has at minimum the scope Code (read and write) for the organization you wish to access
A list of AZURE_DEVOPS_SERVICES organizations that you currently have access to can be found here. Also listed are the projects for each organization.

Enter just the organization, without ‘dev.azure.com’ at the beginning or ‘.visualstudio.com’ at the end. For example, if your organization is ‘dev.azure.com/example-user’ or 'example-user.visualstudio.com’, enter just 'example-user’.
Due to GITLAB's nested group support, when specifying repository it is required to specify the full path. For example <repository>root-level-group/sub-level-group/repo</repository>
scmHost will default to https://gitlab.com for GITLAB

Further documentation of SwaggerHub Integrations can be found here.

Examples

Upload a single API definition

This example uploads the specified API definition in JSON format as a public API in SwaggerHub.

    <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swaggerhub-maven-plugin</artifactId>
        <version>1.0.10</version>
        <executions>
            <execution>
                <phase>deploy</phase>
                <goals>
                    <goal>upload</goal>
                </goals>
                <configuration>
                    <api>PetStoreAPI</api>
                    <owner>jsfrench</owner>
                    <version>1.0.0/version>
                    <inputFile>target/petStoreAPI.json</inputFile>
                    <token>${SWAGGERHUB_APIKEY}</token>
                    <uploadType>inputFile</uploadType>
                </configuration>
            </execution>
        </executions>
    </plugin>

Usage together with `swagger-maven-plugin` (code-first)

This example uses the Swagger Maven plugin to generate the API definition from source code, and then uploads this definition to SwaggerHub.

    <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.10</version>
        <executions>
            <execution>
                <phase>deploy</phase>
                <goals>
                    <goal>upload</goal>
                </goals>
                <configuration>
                    <api>PetStoreAPI</api>
                    <owner>jsfrench</owner>
                    <version>1.0.0</version>
                    <inputFile>target/petStoreAPI.json</inputFile>
                    <token>${SWAGGERHUB_APIKEY}</token>
                    <uploadType>inputFile</uploadType>
                </configuration>
            </execution>
        </executions>
    </plugin>

Upload multiple API definitions

This example uploads all JSON and YAML files from the ${project.basedir}/api-definitions directory to SwaggerHub.

    <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swaggerhub-maven-plugin</artifactId>
        <version>1.0.10</version>
        <executions>
            <execution>
                <phase>deploy</phase>
                <goals>
                    <goal>upload</goal>
                </goals>
                <configuration>
                    <owner>jsfrench</owner>
                    <token>${SWAGGERHUB_APIKEY}</token>
                    <uploadType>directory</uploadType>
                    <definitionDirectory>${project.basedir}/api-definitions</definitionDirectory>
                </configuration>
            </execution>
        </executions>
    </plugin>

Upload multiple API definitions filtered by a regex

This example uploads all JSON and YAML files from the specified directory whose names start with "definition".

    <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swaggerhub-maven-plugin</artifactId>
        <version>1.0.10</version>
        <executions>
            <execution>
                <phase>deploy</phase>
                <goals>
                    <goal>upload</goal>
                </goals>
                <configuration>
                    <owner>jsfrench</owner>
                    <token>${SWAGGERHUB_APIKEY}</token>
                    <uploadType>directory</uploadType>
                    <definitionDirectory>${project.basedir}/api-definitions</definitionDirectory>
                    <definitionFileNameRegex>^definition\w*</definitionDirectory>
                </configuration>
            </execution>
        </executions>
    </plugin>

Upload multiple API definitions via a specified directory and configure GitHub integrations for each definition

    <plugin>
        <groupId>io.swagger</groupId>
        <artifactId>swaggerhub-maven-plugin</artifactId>
        <version>1.0.10</version>
        <executions>
            <execution>
                <phase>deploy</phase>
                <goals>
                    <goal>upload</goal>
                </goals>
                <configuration>
                    <owner>jsfrench</owner>
                    <token>${SWAGGERHUB_APIKEY}</token>
                    <uploadType>directory</uploadType>
                    <definitionDirectory>${project.basedir}/api-definitions</definitionDirectory>
                    <scmToken>${GITHUB_APIKEY}</scmToken>
                    <scmProvider>GITHUB</scmProvider>
                    <repository>my_definitions_repository</repository>
                    <repositoryOwner>githubUser</repositoryOwner>
                    <branch>develop</branch>
                </configuration>
            </execution>
        </executions>
    </plugin>

swaggerhub-maven-plugin's People

Contributors

Stargazers

Watchers

Forkers

mattlk13 woorifis iamzken nick-manasys batwad bhanditz smartbear russelviola joeljons o330oei blearyalarm msgpo borgejh isabella232 neotim sitedata seanpm2001 akshaytha

swaggerhub-maven-plugin's Issues

Can't upload openapi.yaml file to swaggerhub

Can't upload to swagger hub

my plugin configuration

<plugin>
  <groupId>io.swagger</groupId>
  <artifactId>swaggerhub-maven-plugin</artifactId>
  <version>1.0.8</version>
  <executions>
	  <execution>
		  <goals>
			  <goal>upload</goal>
		  </goals>
		  <configuration>
			  <api>DtengAPI</api>
			  <owner>${MY_SWAGGER_USERNAME}</owner>
			  <version>0.0.2</version>
			  <inputFile>target/openapi.yaml</inputFile>
			  <token>${SWAGGERHUB_APIKEY}</token>
			  <definitionType>api</definitionType>
			  <uploadType>inputFile</uploadType>
			  <format>yaml</format>
		  </configuration>
	  </execution>
  </executions>
</plugin>

mvn swaggerhub:upload -X

gives

ERROR] Failed to execute goal io.swagger:swaggerhub-maven-plugin:1.0.8:upload (default-cli) on project rest-event-box: The parameters 'owner', 'uploadType', 'token' for goal io.swagger:swaggerhub-maven-plugin:1.0.8:upload are missing or invalid -> [Help 1]

I notice it doesn't seem to pick up my configurations

[DEBUG] Configuring mojo 'io.swagger:swaggerhub-maven-plugin:1.0.8:upload' with basic configurator -->
[DEBUG] (f) branch = SWAGGERHUB
[DEBUG] (f) definitionType = API
[DEBUG] (f) enableScmIntegration = true
[DEBUG] (f) format = json
[DEBUG] (f) host = api.swaggerhub.com
[DEBUG] (f) isPrivate = false
[DEBUG] (f) port = 443
[DEBUG] (f) protocol = https
[DEBUG] (f) skipFailures = false
[DEBUG] -- end configuration --

When I add back the deploy phase I get a different error

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-deploy-plugin:2.8.2:deploy (default-deploy) on project rest-event-box: Deployment failed: repository element was not specified in the POM inside distributionManagement element or in -DaltDeploymentRepository=id::layout::url parameter -> [Help 1]

I don't really want to configure repository to deploy artificats to since I have no need for that ?

Push to SwaggerHub is formatted incorrectly

There's a formatting issue with the API definition string being saved to SwaggerHub in the upload goal which prevents definition from being rendered correctly in the front-end, e.g. this definition was uploaded via this plugin and isn't rendering https://app.swaggerhub.com/apis/john-french/HackathonTest/1.0.1-SNAPSHOT.

Add support for downloading resolved specs

My OAS3 spec references a domain - when downloading I would like to get that resolved in the same way as the "Export/Download API/JSON/YAML Resolved" menu actions in SwaggerHub

Proxy support

Hi,

as far as I have seen, currently the plugin does not support proxies (e.g. from Maven's settings.xml) ?
Is this planned somehow ?
Would you accept pull requests ?

Plugin upload appears to be successful when misconfigured

When specifying configuration to upload a definition to an on-prem SwaggerHub instance with an incorrect base path, the upload is logged as successful. When verifying in SwaggerHub, the API is unavailable and cannot be found.

Sample output for this issue:

[DEBUG] Configuring mojo 'io.swagger:swaggerhub-maven-plugin:1.0.6:upload' with basic configurator -->
[DEBUG]   (f) api = test-upload
[DEBUG]   (f) basepath = /bad-basepath
[DEBUG]   (f) branch = SWAGGERHUB
[DEBUG]   (f) enableScmIntegration = true
[DEBUG]   (f) format = json
[DEBUG]   (f) host = 11.10.1.96
[DEBUG]   (f) inputFile = target/swagger/swagger.json
[DEBUG]   (f) isPrivate = true
[DEBUG]   (f) owner = CC_Freestyle_Org
[DEBUG]   (f) port = 80
[DEBUG]   (f) protocol = http
[DEBUG]   (f) skipFailures = false
[DEBUG]   (f) token = e**********************************7
[DEBUG]   (f) uploadType = inputFile
[DEBUG]   (f) version = 2.5.14.0
[DEBUG] -- end configuration --
[INFO] Uploading to 11.10.1.96, basepath: /bad-basepath: api: test-upload, owner: swagger-owner, version: 2.5.14.0, inputFile: target/swagger/swagger.json, format: json, isPrivate: true, definitionDirectory: null, definitionFileNameRegex: null, uploadType: inputFile, skipFailures: false, token: e**********************************7
[DEBUG] Executing input file based upload...
[INFO] Uploading API name test-upload version 2.5.14.0
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

Execution config is ignored

Hi,
I've just tried this plugin, but I think there is some problems on configuring the execution:
This is the configuration:

            <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>
                        <owner>gerdzhikov</owner>
                        <api>testApi</api>
                        <version>1.0.0</version>
                        <outputFile>target/petStoreAPI.json</outputFile>
                        <token>eyJ...</token>
                    </configuration>
                </execution>
            </executions>
        </plugin>

Runnig Maven with mvn swaggerhub:download -X fails with the following output:

[DEBUG] -----------------------------------------------------------------------
[DEBUG] Goal: io.swagger:swaggerhub-maven-plugin:1.0.2:download (default-cli)
[DEBUG] Style: Regular
[DEBUG] Configuration: <?xml version="1.0" encoding="UTF-8"?>
<configuration>
<api>${download.api}</api>
<format default-value="json">${download.format}</format>
<host default-value="api.swaggerhub.com">${download.host}</host>
<outputFile>${download.outputFile}</outputFile>
<owner>${download.owner}</owner>
<port default-value="443">${download.port}</port>
<protocol default-value="https">${download.protocol}</protocol>
<token>${download.token}</token>
<version>${download.version}</version>
</configuration>
[DEBUG] =======================================================================
...
[DEBUG] Configuring mojo 'io.swagger:swaggerhub-maven-plugin:1.0.2:download' with basic configurator -->
[DEBUG] (f) format = json
[DEBUG] (f) host = api.swaggerhub.com
[DEBUG] (f) port = 443
[DEBUG] (f) protocol = https
[DEBUG] -- end configuration --
...
[ERROR] Failed to execute goal io.swagger:swaggerhub-maven-plugin:1.0.2:download (default-cli) on project member-module: The parameters 'owner', 'outputFile', 'api', 'version' for goal io.swagger:swaggerhub-maven-plugin:1.0.2:download are missing or invalid -> [Help 1]

When the Maven variables: download.api, download.owner, download.token, download.version and download.outputFile are set in the <properties> section of the POM, than everything work exactley as expected.

Am I doing something wrong, or this is some bug?

Add default lifecycle phases

Neither goal is mapped to a default lifecycle phase so one has to be explicitly defined in the configuration. Each goal should have a sensible default lifecycle phase.

Add support for on-premise SwaggerHub instances

Not able to Upload

Hi,

Am trying to do upload of my proxy to private api governance. But its not uploading. Below is the configuration in the pom.xml:

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swaggerhub-maven-plugin</artifactId>
    <version>1.0.8</version>
    <executions>
        <execution>
            <phase>deploy</phase>
            <goals>
                <goal>upload</goal>
            </goals>
            <configuration>
                <api>demo-apigee</api>
                <owner>Digital-Retail</owner>
                <version>0.2</version>
                <inputFile>sunil/demo-apigee-01.json</inputFile>
                <token>123xyz</token>
                <host>api-governance-corp.falabella.com</host>
                <uploadType>inputFile</uploadType>
                <basepath>v1</basepath>
            </configuration>
        </execution>
    </executions>
</plugin>

Add support to upload apis/domains to a specific project

I seems that the plugin doesn't support uploading to a specific project. If the api/domain already exist, it is properly updated in its project but if it doesn't exist yet, there is now mean to specify in which project it has to be uploaded.

Add support for domains

I've started using domains in my APIs but this tool cannot upload or download them

Unable to make use of 'swaggerhub-maven-plugin' or 'swagger-maven-plugin'

Plugin generates an incomplete JSON schema, more details as follows

Add support for updating default version

We now upload new spec automatically on master build, but it is of little use when we have to manually set it as the default version for it to effectively reach consumers.

Please add an option for bumping the default version on file upload

.

Update Upload/Download Tests to use JUnit4 runner

An issue was found during development that @test(expected = SomeException.class) isn't working as expected. The workaround currently being used is to catch the exception by the Upload/Download execute function and then asserting that a boolean is set to true in the catch block.

Similarly related; when executing Mojo goals within those test classes, params marked as required should cause tests to fail when they are not specified. We have seen on occasions during development and subsequent testing, that isn't the case.

JUnit4 is imported into the project but when the test runner isn't specified, an older version of JUnit is used to run tests. It's hoped that by specifying a runner, that we can solve both issues named above.

Add support for yaml upload/download

cannot download due to ssl handshake

running:
mvn generate-resources and get the below...

Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

extension with syncDirectory and syncFile goal (and get goal)

We have wrapped swaggerhub-maven-plugin to provide the following goals for our organization:

syncFile
syncDirectory
get (similar to download)

This gives us 2 benefits for us;

default values for a number of properties (host, protocol, basepath, owner) that are shared between development teams
synchronization logic instead of simple upload

Point 1 is not interesting to contribute back, but is there any interest in a contribution of syncFile and syncDirectory?

Below is our readme.md for reference:

ORGANISATION-swaggerhub-maven-plugin

Customized version of the swaggerhub-maven-plugin.

Customizations include

ORGANISATION specific defaults to reduce the footprint of the plugin definition in the pom files
Custom upload functionality ensuring that existing formal API versions are not overwritten with an updated specification using the same version

Current version

<plugin>
  <groupId>XX.ORGANISATION.maven</groupId>
  <artifactId>ORGANISATION-swaggerhub-maven-plugin</artifactId>
  <version>3.0.0</version>
</plugin>

Goals

get
syncDirectory
syncFile

get

The get goal can be used to retrieve an API specification from swaggerhub and store it locally for further processing.

Example

<plugin>
  <groupId>XX.ORGANISATION.maven</groupId>
  <artifactId>ORGANISATION-swaggerhub-maven-plugin</artifactId>
  <version>3.0.0</version>
  <executions>
    <execution>
      <phase>generate-sources</phase>
      <goals>
        <goal>get</goal>
      </goals>
      <configuration>
        <api>...</api>
        <version>...</version>
        <outputFile>...</outputFile>
      </configuration>
    </execution>
  <executions>
</plugin>

Configuration

Property	Mandatory	Default	Purpose
api	Y		The name of the API in swaggerhub
version	Y		The semantic version of the API in swaggerhub
outputFile	N	`${project.build.directory}/openapi-spec.json`	The output file

syncDirectory

The syncDirectory goal allows you to synchronize a directory containing specification files with swaggerhub. You will use this sync implementation if you are working code first and generating your specifications. See sync logic for the overall sync logic.
By default this goal will run in the verify phase, so configuration is minimal.
This goal does rely on a number of conventions though, since potentially multiple specifications, both API and DOMAIN, are synchronised.

We expect a certain file format:

[public.|private.]<owner>.<api>[.<majorVersion>]{.json|.yml|.yaml}

If you want your API or DOMAIN to be private on swaggerhub, you need to include the private. prefix; otherwise the specification will be public.
The owner should typically be ORGANISATION and is the swaggerhub owner of the specification. It is required.
The api is the name of the api or domain on swaggerhub. It is required.
You will need to use majorVersion if you simultaneously support more than 1 major version (otherwise the file names will be identical).
There is a choice between all supported formats and supported OAS version for SwaggerHub.

In contrast with thesyncFile goal, we also expect the semantic version of the API or DOMAIN to be present in the specification under $.info.version!

Example

<plugin>
  <groupId>XX.ORGANISATION.maven</groupId>
  <artifactId>ORGANISATION-swaggerhub-maven-plugin</artifactId>
    <configuration>
      <token>...</token>
    </configuration>
  <executions>
    <execution>
      <goals>
        <goal>syncDirectory</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Configuration

Property	Mandatory	Default	Purpose
directory	N	${project.build.directory}/definitionDirectory	The directory where de definitions are found
skip	N	`false`	Skips the execution

syncFile

The syncFile goal allows you to synchronize a single api specificatin file with swaggerhub. You will use this sync implementation if you are writing an openapi spec from scratch. See sync logic for the overall sync logic.

Example

<plugin>
  <groupId>XX.ORGANISATION.maven</groupId>
  <artifactId>ORGANISATION-swaggerhub-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>deploy</phase>
      <goals>
        <goal>syncFile</goal>
      </goals>
      <configuration>
        <api>...</api>
        <version>...</version>
        <file>...</file>
        <private>...</private>
      </configuration>
    </execution>
  </executions>
</plugin>

Configuration

Property	Mandatory	Default	Purpose
api	Y		The name of the API in swaggerhub
version	N	`$.info.version` defined in the file	The semantic version of the API in swaggerhub
file	N	`${project.build.directory}/openapi.yaml`	The file to upload
private	N	`false`	Indicates if the API is private or public
skip	N	`false`	Skips the execution

Sync logic

Snapshot versions

a version is considered to be a snapshot if the version contains a -
are always uploaded to swaggerhub

Release versions

a version is considered to be a release if the version does not contain a -
if a release version does not yet exists in swaggerhub the specification will be uploaded
if a release version already exists it will first be downloaded and compared with the new one that is going to be uploaded
** the build will fail if the 2 specification do not match
** nothing will be uploaded if both specifications are the same

API vs. Domain

The original swaggerhub-maven-plugin differentiates both concepts by explicitly specifing if you are uploading an API or a Domain specification.

The customize plugin applies the following rules:

no paths specified in the specication => Domain
paths specified in the specication => API

Configuration defaults

Global

These are the global configuration properties that can be overridden for every goal

Property	Default	Purpose
host	`swaggerhub.ORGANISATION.XX`	The swaggerhub host name
port	80	The swaggerhub port
protocol	`http`	The swaggerhub protocol
basePath	`v1`	The swaggerhub API base path
owner	`ORGANISATION`	The default API/Domain owner
skipFailures	`false`	Ignore errors when interacting with swaggerhub

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.

swagger-api / swaggerhub-maven-plugin Goto Github PK

swaggerhub-maven-plugin's Introduction

swaggerhub-maven-plugin

Features

Table of contents

Example use cases

Code-first

Design-first

Dependencies

Stable version

Snapshots

Goals

download

Parameters

upload

Parameters

Multi-upload considerations

SCM integration provisioning considerations

Examples

Upload a single API definition

Usage together with swagger-maven-plugin (code-first)

Upload multiple API definitions

Upload multiple API definitions filtered by a regex

Upload multiple API definitions via a specified directory and configure GitHub integrations for each definition

swaggerhub-maven-plugin's People

Contributors

Stargazers

Watchers

Forkers

swaggerhub-maven-plugin's Issues

Below is our readme.md for reference:

ORGANISATION-swaggerhub-maven-plugin

Current version

Goals

get

Example

Configuration

syncDirectory

Example

Configuration

syncFile

Example

Configuration

Sync logic

Snapshot versions

Release versions

API vs. Domain

Configuration defaults

Global

Recommend Projects

Recommend Topics

Recommend Org

Usage together with `swagger-maven-plugin` (code-first)