Swagger Export from .NETCore

Ankur Charan — Sun, 03 Mar 2024 18:39:32 +0000

If you have an ASP.NET Web API project. Chances are you are using Swashbuckle.AspNet.Core to generate swagger documentation for the application.

Now if you need some way to export the swagger api documentation during your build for CI/CD or any other things, this is for you.

Pre-requisite

I am assuming you already have a service from which you can access the swagger JSON/UI.

Generating Swagger on Build

set up dotnet-tools

Run dotnet new tool-manifest at root of your project.
it will create a .config directory with dotnet-tools.json in it. this file will have references to the packages that you've installed.
install swashbuckle cli. run dotnet tool install --local Swashbuckle.AspNetCore.Cli

add post build step

in the project csproj file, add a new post build step.
add step

<Target Name="SwaggerGenerate" AfterTargets="PostBuildEvent">
    <Exec Command="dotnet tool restore" />
    <Exec Command="dotnet swagger tofile --output /path/to/swagger.json .\$(OutputPath)$(AssemblyName).dll v1" />
</Target>

OutputPath and AssemblyName are the project variable, and they have the path to where the build is and dll is generated.
If you have multiple version of the APIs, you can have v1 or v2 in the second command.
Build your csproj and your openapi spec (swagger json) is created during the build.

PostScript

Feel free to reach out to me if you need any help.

linkedin.com/in/ankurcharan
instagram.com/ankurcharan
dev.to/ankurcharan
twitter.com/ankurcharan
ankurcharan.hashnode.dev

ARM template vs Bicep

Ankur Charan — Fri, 01 Mar 2024 23:56:43 +0000

If you've used ARM templates to deploy resources, you must have seen it gets a little messy to maintain if there are a lot of resource.
Bicep is a new language that offers the same capabilities as ARM templates but with a syntax that's easier to use.

You can have modules to divide your arm templates into multiple groups. And you refer the existing resources to get their property values. (You can do this in ARM also, the syntax is easier in Bicep).

You also have a VSCode Bicep extension with intelli-sense to help you write Bicep templates.

ARM to Bicep

with CLI

Once, you have installed bicep-tools, you can use the command az bicep decompile --file <armTemplateFile>.json to convert them to bicep.
Although it is a best effort decompilation. It attempts to convert the file, but there is no guaranteed mapping from ARM template JSON to Bicep. You may need to fix warnings and errors in the generated Bicep file. Or, decompilation can fail if an accurate conversion isn't possible.

manual

Once you have decompiled, you can manually reduce the errors and warnings. Or you can convert the entire template.

If you have worked with ARM template, there format is

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",

  "parameters": {
    // parameters
  },
  "resources": [
    {
      "type": "<resourceType>",
      "apiVersion": "<apiVersion>",
      "name": "<resourceName>",
      "location": "<resourceLocation>",
      "properties": {
        // resource properties
      }
    }
  ],
  "outputs": {
    // trimmed
  }
}

So all of the properties and values are still the same. But the syntax is a little different. (bicep syntax highlighting is not available here)

resource <resourceSymbolicName> '<resourceType>@<apiVersion>' = {
  name: '<resourceName>'
  location: 'resourceLocation'
  properties: {
    // properties
  }
}

Example

Lets say you want to create key azure key vault.

with ARM

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "parameters": {
    "name": {
      "type": "string",
      "metadata": {
        "description": "Required. key vault name."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Required. location of the key vault"
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2023-02-01",
      "name": "[parameters('name')]",
      "location": "[parameters('location')]",
      "properties": {
        "sku": {
          "family": "A",
          "name": "standard"
        },
        "tenantId": "[subscription().tenantId]",
        "enabledForDeployment": true,
        "enabledForTemplateDeployment": true,
        "enabledForDiskEncryption": false,
        "enableSoftDelete": true
      }
    }
  ],
  "outputs": {
    "name": {
      "type": "string",
      "value": "[parameters('name')]"
    },
    "vaultUri": {
      "type": "string",
      "value": "[reference(resourceId('Microsoft.KeyVault/vaults', parameters('name')), '2023-02-01').vaultUri]"
    }
  }
}

This template deploys the key vault and has some properties set for the resource.

with Bicep

You can have the same template as above in Bicep as below. (again no syntax highlighting for Bicep yet)

@description('Required. key vault name.')
param name string

@description('Required. location of the key vault')
param location string

resource kv 'Microsoft.KeyVault/vaults@2023-02-01' = {
  name: name
  location: location
  properties: {
    sku: {
      family: 'A'
      name: 'standard'
    }
    tenantId: subscription().tenantId
    enabledForDeployment: true
    enabledForTemplateDeployment: true
    enabledForDiskEncryption: false
    enableSoftDelete: true
  }
}

// outputs
output name string = kv.name
output vaultUri string = kv.properties.vaultUri

Now if you match, you can see this is just easier to write and the intelli-sense from VSCode Bicep Extension will help alot.

And all the other things that Bicep brings, like modules and using dot operator to access the properties of existing resource.

PostScript

Read more at bicep-documentation. Feel free to reach out to me if you need any help.

linkedin.com/in/ankurcharan
instagram.com/ankurcharan
dev.to/ankurcharan
twitter.com/ankurcharan
ankurcharan.hashnode.dev

Azure API Management DevOps

Ankur Charan — Fri, 07 Oct 2022 09:02:15 +0000

Liquid syntax error: Unknown tag 'endraw'

DEV Community: Ankur Charan

Swagger Export from .NETCore

Pre-requisite

Generating Swagger on Build

set up dotnet-tools

add post build step

PostScript

ARM template vs Bicep

ARM to Bicep

with CLI

manual

Example

with ARM

with Bicep

PostScript

Azure API Management DevOps