Replacements Example

Demonstrates how to use the nv.config file during NightVision's API Discovery to replace unresolved variables in your codebase.

NightVision API Discovery allows you to discover APIs in your codebase and generate API documentation in OpenAPI Format. For more information, see the NightVision documentation.

Prerequisites

• Install the CLI and log in with nightvision login
• Clone this repository: git clone https://github.com/nvsecurity/ReplacementsExample.git

Tutorial

Sometimes, NightVision may not be able to resolve certain variables in your code to generate the most accurate OpenAPI spec. For example, an API prefix (like including the /api/v2 before all API paths) may be read from an environment variable without a default value.

Let's try running the replacement example:

nightvision swagger extract ./ -o openapi-spec.yml -l dotnet --no-upload

It will generate an OpenAPI spec with the unresolved variable, as you can see below:

components: {}
info:
  description: Autogenerated by API ENVY
  title: OpenAPI 3 specification
  version: "0.1"
openapi: 3.0.0
paths:
  # Notice how the unresolved variable is included in the path. 
  # It should be `/api/v2`, based on the appsettings.json file.
  /ApiPrefix:
    get:
      operationId: ApiPrefix_GET
      responses:
        default:
          description: Default response
      x-name: ApiPrefix_GET
      x-source: Program.cs~~14
    x-name: ApiPrefix
servers:
  - description: Default server
    url: https://localhost:9000

That command will also generate an nv.config file. The nv.config file will look like this:

{
  "replacements": {
    "Microsoft.AspNetCore.Builder.WebApplication.Services.GetRequiredService().Value.ApiPrefix": null
  }
}

If you populate that variable with the proper prefix, it should look like this:

{
  "replacements": {
    "Microsoft.AspNetCore.Builder.WebApplication.Services.GetRequiredService().Value.ApiPrefix": "api/v2"
  }
}

You can run the following command to generate the OpenAPI spec with the correct prefix:

nightvision swagger extract ./ -o openapi-spec.yml -l dotnet --no-upload --config nv.config

The generated OpenAPI spec will now include the correct prefix:

components: {}
info:
  description: Autogenerated by API ENVY
  title: OpenAPI 3 specification
  version: "0.1"
openapi: 3.0.0
paths:
  # Notice how the path is now `/api/v2` instead of `/ApiPrefix`
  /api/v2:
    get:
      operationId: ApiPrefix_GET
      responses:
        default:
          description: Default response
      x-name: ApiPrefix_GET
      x-source: Program.cs~~14
    x-name: ApiPrefix
servers:
  - description: Default server
    url: https://localhost:9000

Appendix

Understanding this repository

In the case of this repository, the ApiPrefix is read from the appsettings.json file.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApiOptions" : {
    # This is where the configuration option is set
    "Prefix" : "api/v2"
  }
}

And in the code, the ApiPrefix is read from the configuration file:

IOptions<ApiOptions> options = app.Services.GetRequiredService<IOptions<ApiOptions>>();

var api = app.MapGroup(options.Value.ApiPrefix); 

In this case, as of version 0.6.1 of the CLI, NightVision will not be able to resolve the value of the variable.