3. Swagger or WSDL File

Of course the API-Definition as Swagger/WSDL is key for the state of the API and changes to it must be handled like any other API-Property defined "manually" in the API-Configuration.

That means, when the desired API-Definition is changed, it must be recognized as a change and replicated into the API-Manager. The program is doing exactly this for you.

How Swagger-/WSDL-Definition changes are detected?

The Swagger-/WSDL-File definition itself isn't parsed field by field to identify changes, instead the program is using internally a Byte-Comparison. In other words: Even a small change, like a an additional whitespace, or the line-ending-format (DOS vs. UNIX) is recognized as a change between the actual and the desired state and will lead to the needed actions to get the new Swagger-File into API-Manager.

However, as the program is designed to be part of a CI/CD-Pipeline working based on a Version-Control-System it's unlikely that unwanted changes are made to the Swagger-Definition.

Options to provide the API-Definition-File

You have three options to provide the Swagger-File to the tool:
1. Local filesystem
Provide a relative or absolute path to the Swagger-File. This path must be relative to the API-Configuration file.
Examples:
-a sample/petstore.json
-a /home/git/any/path/myswagger.json

2. Remote URL reference by file
In cases you want reference a Remote-Swagger file, but still requiring to version-control this information, create a file such as:
any-name-of-my-swagger.url
In the first line of the file provide the URL to the JSON-Based Swagger- or WSDL-File. This may optionally include username/password for a HTTP-Basic authentication. Format:
[myuser/mypasswd@]https://any.host.com/path/to/swagger.json
Example including username and password:
chris/myverysecurepassword@https://any.host.com/path/to/swagger.json
⚠️ Make sure to quote the URL properly when calling on command-line/script!

It is important to know, that the tool running on a CI/CD-Slave must have access to that endpoint in order to download the API-Definition. It is NOT the API-Manager downloading the file. Proxy-Support is not supported.

3. Remote URL interactively provided
In cases where you want to execute the tool interactively and just simply using a URL, you can provide it in the same format to the -a parameter.
Format:
-a [myuser/mypasswd@]https://any.host.com/path/to/swagger.json
Example with the optionally provided username & password:
-a chris/abc123@https://any.host.com/path/to/swagger.json
⚠️ Make sure to quote the URL properly when calling on command-line/script!

The API-Definition can be either provided as parameter "-a" or directly in the API-Configuration file as shown in this example:

{
    "name": "Minimal API",
    "path": "/minimal/api/v1",
    "state": "unpublished",
    "version": "1.0.0",
    "apiDefinition": "samples/petstore.json",
    "organization": "API Development"
}

Supported API-Specifications

The following definitions/specifications are supported:

Specification	Supported	Comment
OpenAPI 3.0	Yes	Requires API-Manager 7.7-20200130
Swagger 2.0	Yes	Fully supported
Swagger 1.2	Yes	Requires Swagger-Promote >=1.6.7
WSDL	Yes	Parameter BackendBasepath is not supported for WSDL