The basics

If you're familiar with Swashbuckle or NSwag you should be right within your comfort zone, the configuration and usage here is just as simple.

First off let's take a look at what we have:

The existing functionality

NSwag basic annotations apply, as long as we're speaking of method level annotations. So:

[SwaggerResponse]
[SwaggerTag]
[SwaggerIgnore]
[SwaggerDefaultResponse]
[OpenApiIgnore]

Pretty simple stuff.

New annotations

In addition, there are new annotations available in the NSwag.Annotations.AzureFunctionsV2 namespace. Again, these are applied on method level:

[SwaggerAuthorize(AuthScheme.Basic)]
[SwaggerFormData("myField", Required = true, Type = typeof(string), Description = "a form field")]
[SwaggerFormDataFile(Name = "myFile", MultiFile = false, Description = "a file field")]
[SwaggerQueryParameter("myQueryParam", Required = false, Type = typeof(int), Description = "number")]
[SwaggerRequestBodyType(typeof(MyObject))]
[SwaggerRequestHeader("x-my-header")]

More detailed documentation is available for each of the new attributes, check the sidebar.

A simple Swagger definition

The following subject is presented in a tutorial form and is fully available and downloadable as a finished project from https://github.com/Jusas/NSwagAzureFuncAppExample1

Ok, so in order to output a Swagger JSON you need to do three things:

1. Annotate your methods
2. Configure your Swagger Generator
3. Generate and serve your generated JSON

First step is easy enough. Let's create a new Function App (Http trigger) called ExampleFunctionApp. Next go ahead and add the NSwag.SwaggerGeneration.AzureFunctionsV2 package from Nuget to the project. You can also wipe out the default generated Function1 class and copy paste this one to a new class file called ExampleFunctions.cs.

using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;
using NSwag.Annotations;
using NSwag.Annotations.AzureFunctionsV2;
using NSwag.SwaggerGeneration.AzureFunctionsV2;

namespace ExampleFunctionApp
{
    public static class ExampleFunctions
    {
        public class MyGreeting
        {
            public string Message { get; set; }
        }

        [SwaggerResponse(200, typeof(MyGreeting))]
        [SwaggerQueryParameter("name", true, typeof(string), "The caller's name")]
        [FunctionName("hello")]
        public static async Task<IActionResult> Hello(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "hello")]
            HttpRequest req,
            ILogger log)
        {
            return new OkObjectResult(new MyGreeting() {Message = req.Query["name"]});
        }
    }
}

Ok so now you've got step 1 covered, now steps 2 and 3: configure your swagger generator. This is easiest done in a single Function that generates the JSON and serves it.

So go ahead and add another Function:

[SwaggerIgnore]
[FunctionName("swagger")]
public static async Task<IActionResult> Swagger(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "swagger")]
    HttpRequest req,
    ILogger log)
{
    var settings = new AzureFunctionsV2ToSwaggerGeneratorSettings()
    {
        Title = "My Function App Swagger",
        Description = "Here be dragons!",
        Version = "1.0"
    };
    var generator = new AzureFunctionsV2ToSwaggerGenerator(settings);
    var swaggerDoc = await generator.GenerateForAzureFunctionClassAsync(typeof(ExampleFunctions));
    var json = swaggerDoc.ToJson();
    return new OkObjectResult(json);
}

That's it! Now go ahead and run, browse to http://localhost:7071/api/swagger and there's your Swagger JSON.

Next steps

Obviously when authentication and HttpExtensions come into the picture, more configuration is required. Also if you wish to serve Swagger UI from the Functions you'll need to include the files in your Function and write some lines of code to serve them properly. You can find a crude example of this from the test project in this repository, NSwag.SwaggerGeneration.AzureFunctionsV2.Tests.HttpExtensionsTestApp.