Plumsail.Swashbuckle.MicrosoftPowerAutomate 1.4.0

dotnet add package Plumsail.Swashbuckle.MicrosoftPowerAutomate --version 1.4.0
NuGet\Install-Package Plumsail.Swashbuckle.MicrosoftPowerAutomate -Version 1.4.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Plumsail.Swashbuckle.MicrosoftPowerAutomate" Version="1.4.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Plumsail.Swashbuckle.MicrosoftPowerAutomate --version 1.4.0
#r "nuget: Plumsail.Swashbuckle.MicrosoftPowerAutomate, 1.4.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Plumsail.Swashbuckle.MicrosoftPowerAutomate as a Cake Addin
#addin nuget:?package=Plumsail.Swashbuckle.MicrosoftPowerAutomate&version=1.4.0

// Install Plumsail.Swashbuckle.MicrosoftPowerAutomate as a Cake Tool
#tool nuget:?package=Plumsail.Swashbuckle.MicrosoftPowerAutomate&version=1.4.0

Introduction

This package was ported to NET5 and 6.x version of the swagger from Swashbuckle.AspNetCore.

Usage

Nuget package

Install-Package Plumsail.Swashbuckle.MicrosoftPowerAutomate

Activate support

Add this extension call to SwaggerGenOptions.

services.AddSwaggerGen(c =>
{
    c.GenerateMicrosoftExtensions();
});

It has optionals arguments:

  • FilePickerCapabilityModel filePicker for activate File picker capability
  • ConnectorMetadataModel connectorMetadata for add x-ms-connector-metadata extension

Metadata

Metadata attribute can be used for methods, parameters and properties

Example definition

Code:

public class MetdataAttributeClass
{
    [Metadata("Summary", "Description", VisibilityType.Advanced)]
    public string Name { get; }

    public MetdataAttributeClass(string name)
    {
        Name = name;
    }
}

Generated swagger:

"MetdataAttributeClass": {
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "readOnly": true,
            "x-ms-visibility": "advanced",
            "x-ms-summary": "Summary",
            "description": "Description"
        }
    }
}

Example controller

Code:

[Route("api/MetadataAttribute")]
    public class MetadataAttributeController : Controller
    {
        [HttpPost]
        [Metadata("FriendlyAction", "ActionDescription", VisibilityType.Important)]
        public MetadataAttributeClass Post([FromBody][Metadata("FriendlyParameter", "ParameterDescription")] string value)
        { ... }
}

Generated swagger:

"/api/MetadataAttribute": {
    "post": {
        "x-ms-visibility": "important",
        "summary": "FriendlyAction",
        "description": "ActionDescription",
        "parameters": [...],
        ...

Dynamic value lookup

Dynamic value lookup can be used for properties and parameters

Example

Code:

public class DynamicValueController : Controller
{
    [HttpGet]
    [Route("api/dynamic")]
    public void Get
    (
        [DynamicValueLookup("opId", "id", "name", parameters: "test=static&test2={dynamic}")]
        string dynamicValue
    ) { }
}

Swagger:

"/api/dynamic": {
    "get": {
        "tags": [ "DynamicValue" ],
        "operationId": "ApiDynamicGet",
        "parameters": [
            {
                "name": "dynamicValue", "in": "query",
                "required": false,
                "type": "string",
                "x-ms-dynamic-values": {
                    "operationId": "opId",
                    "value-path": "id",
                    "value-title": "name",
                    "parameters": {
                        "test": "static",
                        "test2": {
                            "parameter": "dynamic"
                        }
                    }
                }
            }
        ],
        "responses": {
            "200": {
                "description": "Success"
            }
        }
    }
}

Dynamic value lookup capability

Dynamic value lookup capability can be used for parameters

Example

Code:

public class DynamicValueCapabilityController : Controller
    {
        [HttpGet]
        [Route("api/capability")]
        public void Get 
        (
            [DynamicValueLookupCapability("capabilityName", "id", "name", parameters: "isFolder=true&test=static&test2={dynamic}")]
            string dynamicValue
        ){ }
    }

Swagger:

"/api/capability": {
    "get": {
        "tags": [
            "DynamicValueCapability"
        ],
        "operationId": "ApiCapabilityGet",
        "parameters": [
            {
                "name": "dynamicValue",
                "in": "query",
                "required": false,
                "type": "string",
                "x-ms-dynamic-values": {
                    "capability": "capabilityName",
                    "value-path": "id",
                    "value-title": "name",
                    "parameters": {
                        "isFolder": true,
                        "test": "static",
                        "test2": {
                            "parameter": "dynamic"
                        }
                    }
                }
            }
        ],
        "responses": {
            "200": {
                "description": "Success",
                "schema": {
                    "$ref": "#/definitions/DynamicValueLookupCapabilityClass"
                }
            }
        }
    }
}

Dynamic schema lookup

Dynamic schema lookup can be used for properties, parameters and classes

Example

Code:

[DynamicSchemaLookup("DynamicSchemaOpId", "schema", "param1={test}&param2=test")]
public class DynamicSchemaLookupClass : Dictionary<string, object> { }

Swagger:

"DynamicSchemaLookupClass": {
    "type": "object",
    "properties": { },
    "additionalProperties": {
        "type": "object"
    }
    "x-ms-dynamic-schema": {
        "operationId": "DynamicSchemaOpId",
        "value-path": "schema",
        "parameters": {
            "param1": {
                "parameter": "test"
            },
            "param2": "test"
        }
    }
}

File picker capability

Note: file picker design is not final, might change in the future from Microsoft's side

File picker capability can be used in GenerateMicrosoftExtensions method

Examples

Code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();

    var filePicker = new FilePickerCapabilityModel
    (
        new FilePickerOperationModel("InitialOperation", null),
        new FilePickerOperationModel("BrowsingOperation", new Dictionary<string, string> {{"Id", "Id"}}),
        "Name",
        "IsFolder",
        "MediaType"
    );
    
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
        c.GenerateMicrosoftExtensions(filePicker);
    });
}

Swagger:

"x-ms-capabilities": {
    "open": {
        "operation-id": "InitialOperation"
    },
    "browse": {
        "operation-id": "BrowsingOperation",
        "parameters": {
            "Id": {
                "value-property": "Id"
            }
        }
    },
    "value-title": "Name",
    "value-folder-property": "IsFolder",
    "value-media-property": "MediaType"
}

Parameters

Current solution for parameters is that they are given as a query string, dynamic parameters are passed in braces {}

Examples

Code:

parameters: "staticParam=true"

Swagger:

"parameters": {
    "staticParameter": true
}

Code:

parameters: "dynamicParam={previuoslyDefinedParam}"

Swagger:

"parameters": {
    "dynamicParam": {
        "parameter": "previouslyDefinedParam"
    }
}

Code:

parameters: "staticParam=true&dynamicParam={previouslyDefinedParam}&moreDynamic={example}"

Swagger:

"parameters": {
    "staticParam": true,
    "dynamicParam": {
        "parameter": "previouslyDefinedParam"
    },
    "moreDynamic": {
        "parameter": "example"
    }
}

Trigger

Trigger used for mark route as Trigger subscribe method for Power Automate

Examples

Code:

[Route("api/[controller]")]
[ApiController]
public class TriggerController : ControllerBase
{
    [HttpPost]
    [Trigger(TriggerType.Subscription, typeof(TriggerAnswerModel), "TriggerFriendlyName")]
    public IActionResult TriggerSubscription([FromBody] SubscriberCreateRequest subscriber)
    {
        // Register flow and generate SubscriberId and URL for unsubscribe
        return Created(unsubscribeUrl, subscriberId);
    }
}

Swagger:

"/api/Trigger": {
    "post": {
        "x-ms-trigger": "signle"
    },
    "x-ms-notification-content": {
        "description": "TriggerFriendlyName",
        "schema": {
            "$ref": "#/definitions/TriggerAnswerModel"
        }
    }
}

Connector metadata

Connector metadata can be used in GenerateMicrosoftExtensions method

Examples

Code:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
        c.GenerateMicrosoftExtensions(connectorMetadata: new ConnectorMetadataModel(
            "http://www.example.com", // Link to your site
            "http://www.example.com/privacy", // Link to your privacy policy
            new [] { "Category1", "Category2" } // Categories for connector
        ));
    });
}

Swagger:

"x-ms-connector-metadata": [
    {
      "propertyName": "Website",
      "propertyValue": "http://www.example.com"
    },
    {
      "propertyName": "Privacy policy",
      "propertyValue": "http://www.example.com/privacy"
    },
    {
      "propertyName": "Categories",
      "propertyValue": "Category1;Category2"
    }
]
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.4.0 2,028 9/9/2022
1.3.0 52,709 2/16/2022
1.2.0 375 12/9/2021
1.1.0 2,017 11/26/2021
1.0.0 2,970 11/25/2021

v 1.4.0
 - Updated for compability with latest Swashbuckle

v 1.3.0
 - Added ConnectorMetadataModel parameter in GenerateMicrosoftExtension to support x-ms-connector-metadata extension

v 1.2.0
 - Added DynamicListLookupAttribute to support x-ms-dynamic-list extension
 - Now null values not writed to extensions
 - Removed operation metadata from body parameter

v 1.1.0
 - Added DynamicLookupPropertiesAttribute to support x-ms-dynamic-properties extension
 - Added CallbackUrlAttribute to support x-ms-notification-url extension