Nswag: Implement Support for Azure Functions Project or Assembly in NSwag and Studio

[SebastianAtWork]

Hi,
it would be really cool if NSwag and NSwag Studio could generate a swagger definition for an Azure Function App csproj or dll. I will try and look into the code myself, maybe i can implement it. But of course, any help would be appreciated.

[RicoSuter]

You could probably implement that with the help of a SwaggerGenerator instance and do it the same way as the AspNetCoreToSwagger generator, etc.

[SebastianAtWork]

Thanks. I try to implement it that way. Already got a copy of the necessary classes and renamed them. I have vacation for the next 2 weeks, so lots of time to code ;)

[jeremyVignelles]

I'm also interested in that implementation, I can try it if you want 🙂
Please keep me updated

[RicoSuter]

I think this should be a new project "NSwag.SwaggerGeneration.AzureFunctions" (or AzureFunction?) with an own reflection based generator which is then referenced by NSwag.Commands and used in new commands...

[simeyla]

@RSuter Sometimes I feel you are like a 'reverse stalker'. You always seem to be exactly one step ahead of what I need at any given time :-) Thank you for all your work on this project.

You probably have already seen this, but there's an article from @wobba (Mikael Svenson) facing the same issue who put together a project to do exactly this. Currently it runs as an azure function itself using runtime reflection.

Article: https://www.techmikael.com/2017/08/maybe-most-useful-azure-function-ever.html
Repo: https://github.com/wobba/AzureFunction-SwaggerDefinition

I'm extremely new to Azure Functions, but it appears to do the trick and gave me a swagger file which I could feed into NSwag and get an Angular client out that appears to have all the correct input and output types.

I only had to make minor changes to his Swagger.cs file (this is the generator) to get it running. Essentially just needed to switch to using the newer 'ProducesResponseType' attribute, rather than ResponseType.

        if (returnType == typeof(IActionResult))
        {
            var responseTypeAttr = (ProducesResponseTypeAttribute)methodInfo
                .GetCustomAttributes(typeof(ProducesResponseTypeAttribute), false).FirstOrDefault();
            if (responseTypeAttr != null)
            {
                returnType = responseTypeAttr.Type;
            }
            else
            {
                returnType = typeof(void);
            }
        }

This will have to do for me for now, but wanted to put this here in the interim. Perhaps he would be interested in working together?

[wobba]

@simeyla feel free to create a PR for the change, or I'll try to update the code myself when I have time :)

[jeremyVignelles]

I did try that method but I gave up after it tried to interpret System.Array as an entity type rather than a T[].
I then saw this issue and decided to wait, because it was not yet a top priority for us.

I think that the idea of having an azure function exposing NSwag's generator can be a good idea, but I fear that adding dependencies like that to azure functions could lead to version conflict.

Anyway, @SebastianAtWork did you have any progress?

[SebastianAtWork]

@jeremyVignelles A little bit, but not enough to really be noteworthy. Other Projects kind of had more priority, sorry. If you want to take over, feel free. @simeyla link to AzureFunction Swagger Definition Generator seems really cool, I´ll give that a try, Maybe that makes the need for the generator obsolete.

[SebastianAtWork]

@simeyla After some playing with AzureFunction-SwaggerDefinition: Really cool idea, unfortunately it still lacks a lot of details (for example: if 2 functions share common contract classes, it generates 2 definitions).
Its currently more of a "how to" with a really cool idea.
But the reflection logic itself would be a good starting point for an nswag generator.
And the Author seems to know his Reflect-fu, maybe he really would want to work on this project.

[RicoSuter]

The https://github.com/wobba/AzureFunction-SwaggerDefinition repo contains lots of custom logic for parameters and DTOs which could be directly replaced by NSwag code (SwaggerGenerator class) so that they just work for all special cases and scenarios... but the function lookup (i.e. detection of routes, etc.) must be implemented according to how functions behave. Unlike ASP.NET Core I think there is no API Explorer api - so this has to be implemented by hand I think.

[simeyla]

@SebastianAtWork It's also worth remembering that version 1 of functions already has Swagger support from Microsoft built in.

I'm looking to get up and running with functions with the simplest possible APIs (for proof of concept type testing) so it looks like what @wobba has done is good enough for me.

Also I'm probably going to abandon functions as quickly as I've tried to adopt them. They don't support 64 bit Node (that I need for one thing), and the concurrency attributes like [Singleton] don't work on the pay-as-you-go plan. So I may as well just stick with a dedicated VM and WebAPI.

[TomBonnerAtTFL]

Okay, just for the next person to try this, I got a NSwag.SwaggerGeneration.AzureFunctions project working all the way up to generating a simple function definition, the problem however is that the Azure methods return IActionResult which contains an object, and you load post parameters with Content.ReadAsAsync<PostData>();.

This makes reflection pretty much impossible given we'd have to do really vauge method-body parsing so that's me out of ideas. If anyone's got another direction I can try, just shout.

[RicoSuter]

The only way to implement that is by adding attributes like ProducesResponseTypeAttribute like asp.net core does...

[Jusas]

Hey there, this may be the right time to introduce my little pet projects that does pretty much exactly what you're looking for: NSwag.AzureFunctionsV2 and AzureFunctionsV2.HttpExtensions. A demo of both in action is here.

Been working on them for a couple of months, they're two projects that supplement each other quite nicely. The NSwag.AzureFunctionsV2 may be something @RSuter may be interested in merging into NSwag, currently it's a set of new annotations and a SwaggerGenerator implementation tailored for HTTP triggered Azure Functions. In the meanwhile my plan is to keep it as a separate package and somewhat up-to-date with NSwag releases.

Using this in production is on your own discretion though - it hasn't been used in any serious project yet. Originally I created these projects to enable creating "cheapskate APIs", ie. APIs that can run fully on Consumption tier Functions being very cost-efficient and scalable right down to the core.

[RicoSuter]

@Jusas this looks really interesting! Thank you for sharing... maybe we should get in contact for a personal call to check how we want to proceed?

[Jusas]

@RSuter Sorry for the delayed reply, at this time I think I want to slow down a bit and have this used in a project or two to iron out any problems. The NSwag generator pretty much walks hand in hand with the HttpExtensions project (although is not a direct dependency) and I'd just like to implement something real with the both of them and identify any bugs and pain points before I'm comfortable of declaring this ready for production use. In the meantime I'd like to keep all this available for public use for those who like to be early adopters.

[zuckerthoben]

Interesting stuff. As of the status of this issue and the last comments I guess the functionality is not yet implemented/merged in NSwag?
@RicoSuter @Jusas

[Jusas]

Interesting stuff. As of the status of this issue and the last comments I guess the functionality is not yet implemented/merged in NSwag?
@RicoSuter @Jusas

For now we've kept them separate, and I'm personally fine with this arrangement. I wouldn't be able to contribute in the same exact pace as Rico anyway. I also want to maintain support for AzureFunctionsV2.HttpExtensions, which is my utility package for HttpTrigger Functions, which would further add the burden of yet another dependency to Rico if he were to maintain the NSwag.AzureFunctionsV2 package.

I try my best to keep my package up-to-date with the latest NSwag version (currently built and tested against NSwag v13.0.4) but it can lag a little bit behind.

Both packages are available as nugets:
https://www.nuget.org/packages/AzureFunctionsV2.HttpExtensions/
https://www.nuget.org/packages/NSwag.SwaggerGeneration.AzureFunctionsV2/

[shibayan]

I want to use the Command Line app to generate an Open API definition for Azure Functions. Is there a good way?
Examining the code, it appears that it needs to be added to NSwag.Command.

[mdarefull]

@RicoSuter: Any update on this issue? it has been over a year since its most active contribution from @Jusas, but it seems there hasn't been any contribution to any of the two projects for over half a year.

[RicoSuter]

Ideally we’d pull this over and maintain it with the whole solution.. lots of work - probably ill do that if i need it in my professional work. Currently too much work to do in my free time

[Jusas]

Chiming in here, I really haven't had the time nor the inclination to work on this and seeing how little I've used it and having to play catch up with both NSwag and Functions (running V3 now) I might as well basically archive my repo. The whole development has been on my free time, which I nowadays use for many other things. It's sad, but that's the way things are.

[RicoSuter]

Same here, also tried to use azure functions for web apis with openapi but there were so many problems (not necessarily with your libs) that we moved to a regular asp.net core app and docker hosting...

[jeremyVignelles]

That's the fate of many Open source projects. Thanks for the contribution and take care ! 🙂

[Jusas]

Same here, also tried to use azure functions for web apis with openapi but there were so many problems (not necessarily with your libs) that we moved to a regular asp.net core app and docker hosting...

Overall a good choice. Functions are fine for a little dabbling when you happen to need a HTTP endpoint but you'll soon realize that a full ASP.NET Core API is generally much easier to work with.

That's the fate of many Open source projects. Thanks for the contribution and take care ! 🙂

Thanks! It always pains to drop maintenance on a project that people use but then again, it's also possible for anyone to pick it up and continue where I left off.

[RicoSuter]

Thanks! It always pains to drop maintenance on a project that people use but then again, it's also possible for anyone to pick it up and continue where I left off.

I agree, anyway thank you very much and let's see what happens, if there are many request we'll get in touch again and see what we can do...