This package was created to extend swagger generation in order to support functionality required for MS Flow. Documentation.
Inspired by T-Rex
Built upon Swashbuckle.AspNetCore.
Install-Package Swashbuckle.AspNetCore.MicrosoftExtensions
Metadata attribute can be used for methods, parameters and properties
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"
}
}
}
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 can be used for properties and parameters
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 can be used for parameters
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 can be used for properties, parameters and classes
Code:
[DynamicSchemaLookup("DynamicSchemaOpId", "schema", "param1={test}¶m2=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 can be used in GenerateMicrosoftExtensions method
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"
}
Current solution for parameters is that they are given as a query string, dynamic parameters are passed in braces {}
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"
}
}