4. Staging Concept

Normally customers do have multiple stages or environments, which may have different requirements in terms of security, versioning, etc. and it's obvious, that the program must support it.
As the Swagger-Definition & API-Config becomes the single source of truth, it must be the truth for all stages/environments and some environments need different settings. For instance stronger security rules in Production vs. Pre-Production or other Custom-Policies in the Cloud vs. On-Premise.

Apply staging

The program is using overrides to apply different settings per stage to avoid, that the API-Developer needs to maintain multiple files with almost the same content. The idea is just to provide the "Delta" API-Config for the stage.
By using the option -s (stage) and the stage-id you inject the stage config. An example would be:

scripts/run-swagger-import.sh -s prod -a samples/petstore.json -c samples/minimal-config.json -h localhost -u apiadmin -p changeme

With that, the program is looking for an Production-API-Config override-file placed side by side to the main API-Config. That means you need to have the following files in your directory:

petstore.json                 # The API-Swagger-Definition  
minimal-config.json           # The Main-API-Config file with default settings  
minimal-config.prod.json      # The Config-File with settings for the prod environment  

Environment settings

Additionally, also environment-specific parameters (such as the host, the users, handling of client apps, etc.) might be different from stage to stage. For instance, it might be desired to ignore Client-App-Handling in the production stage, but have it enabled for easier tests in all Pre-Production stages. Also, this is supported by providing so called: Environment-Properties.
Learn more on this page how this works

What is NOT possible / Limitations

You can basically override in your stage-file everything you can define in the main-contract.

But, "Deep"-Merge is unfortunately not supported. Let's assume the following main-config:

{
   "name":"Any API-Name",
   "path":"/my/path/to/api",
   "state":"published",
   "version":"1.0.0",
   "organization":"API Development",
   "securityProfiles":[
      {
         "name":"_default",
         "isDefault":true,
         "devices":[
            {
               "name":"API Key",
               "type":"apiKey",
               "order":0,
               "properties":{
                  "apiKeyFieldName":"KeyId",
                  "takeFrom":"HEADER",
                  "removeCredentialsOnSuccess":"false"
               }
            }
         ]
      }
   ]
}

And you would like to change the API-Key field: takeFrom to QUERY instead of HEADER for the Security-Profile. For that requirement, let's assume you have created an API-Config-File: minimal-config.prod.json like this:

{
   "securityProfiles":[
      {
         "devices":[
            {
               "name":"API Key",
               "type":"apiKey",
               "order":0,
               "properties":{
                  "takeFrom":"QUERY"
               }
            }
         ]
      }
   ]
}

That config will lead to an error, as the security profile in the stage-config is read on it's own and therefore incomplete. You need to add the complete profile-information. This limitation applies for all profiles, such a Outbound-, CORS, etc.

Perhaps in a later version deep-merge support will be added.