Swagger API changelog

A gradle plugin, developed by Sonalake that scans a nexus repository for historical versions of a swagger.json for some project, and produces an asciidoc formatted changelog from it.

Assumes that:

• There is a history of swagger API json documents on nexus
• The versions can be sorted by their version id
• It is only the complete versions that are to be considered (e.g only 1.4.1 and not any 1.4.1-RC1)

However, you can include a local file to act as the latest snapshot, that will be considered as the last version in the chain.

What is generated?

The following files are created in the target directory:

• change-log.adoc - an index doc that includes all of the underlying generated documents.
• change-log-${oldVersion}-${newVersion}.adoc - a specific file for each version step.

Each version-to-version file comes in this format:

• A list of the new / deprecated endpoints
• A list of all the endpoints with changes in any of the parameters, return types.

This includes both completely new parameters/properties, and also changes to existing entities.

For example:

 
=== Version 1.2.2 to 1.3.0

==== New Endpoints

* `POST` /admin/config/flushcache Manually flush the cache

==== Deprecated Endpoints

==== Changed Endpoints

`POST` /orders Creates new order +
 Parameters

----
    Insert orderRequest.hardwareDetails //Details on the hardware within the site
    Insert orderRequest.sourceSiteDetails //Details on the source site
    Insert orderRequest.targetSiteDetails //Details on the source site
    Delete orderRequest.endCustomerSiteDetails //Details on the hardware within the site
    Delete orderRequest.sourceCircuitDetails //Details on the source site
    Delete orderRequest.targetCircuitDetails //Details on the source site
----

Gradle usage

NOTE: depends on at least gradle 4.10

Task: generateChangeLog

The task to call that will generate the above changelog files is generateChangeLog

To use the plugin, you need to add this to your build.gradle

Using the plugins DSL:

plugins {
  id "com.sonalake.swagger-changelog" version "1.0.0"
}

Or, using legacy plugin application:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.com.sonalake:swagger-changelog-gradle-plugin:1.0.0"
  }
}

apply plugin: "com.sonalake.swagger-changelog"

The configuration for this plugin is

swaggerChangeLog {
   
    // this is assumed to be in the json format
    groupId = 'com.sonalake'
    artifactId = 'app-server'
    classifier = 'swagger'

    // where to find the nexus repo
    nexusHome = 'http://atlanta.sonalake.corp:8081/nexus'
    repositoryId = 'releases'
    
    // where to store the changelog
    targetdir = "${buildDir}/apidoc/swagger-changelog"
    
    // (optional) if your build has a "current snapshot 
    // version" then add it to the version history as 
    // the last version - it will be included no matter
    // what the version id is.
    snapshotVersionFile = "${buildDir}/swagger.json"
    
    
    // (optional) from what level should the chapters 
    // start at. By default, they will start at level 3, 
    // i.e. "==="
    baseChapterLevel = 3

    // (optional) the app assumes, for backwards-compatibility
    // reasons that the target nexus is version 2set this to true
    // if the target is version 3+
    isNexusVersion3 = true
}

CI

There are two github actions defined for this:

• CI Build - This is run on every commit to the main and development branches, and is limited to testing and coverage.

• Publish Plugin - This is run by triggering the action manually, and will - for non SNAPSHOT versions - sign the jars and publish them to the public maven repo and gradle.

  You will need access to the github secrets to run these actions, but you won't need to if you want to submit a pull request.