extension with syncDirectory and syncFile goal (and get goal)

[Wimpi]

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;

1. default values for a number of properties (host, protocol, basepath, owner) that are shared between development teams
2. 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

See also global configuration

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

See also global configuration

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

See also global configuration

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

[ymajoros]

We are really interested. Can you provide a pull request? 😃