Are people seriously using this in production code?

[SyntaxWarrior]

I don't mean to be mean or disrespectful, but looking at the examples such as:

// Add these three attribute classes below
[OpenApiOperation(operationId: "greeting", tags: new[] { "greeting" }, Summary = "Greetings", Description = "This shows a welcome message.", Visibility = OpenApiVisibilityType.Important)]
[OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
[OpenApiParameter("name", Type = typeof(string), In = ParameterLocation.Query, Visibility = OpenApiVisibilityType.Important)]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(Greeting), Summary = "The response", Description = "This returns the response")]

[Function("Net60HttpTrigger")]
public static async Task<HttpResponseData> Run([HttpTrigger(AuthorizationLevel.Function, "get", Route = "greetings")] HttpRequestData req,
    FunctionContext executionContext)
{
}

Besides being a hard to read these are horrible to maintain. In previous versions when one could use swagger the documentation was made from what was actually in the code. With the above everything from the request parameters to the response data is in attributes. How long is it going to take before one of those is out of sync with the actual request parameters or response types.

I mean this might be fine for a hello world or some simple one developer site with few requests.. But for a normal sized site with multiple developers and 100s or more different methods being exposed.. This will just be one big mess.

I tried to see if there is some type of roadmap where auto generation of the specifications is in the future (which I dearly hope) but I could not find anything about that.

.. or am I missing some big point here which makes this all very useful?

[justinyoo]

@SyntaxWarrior Thanks for your comment! I truly understand what you feel the pain. But before that, let's clarify what I understood from your words.

Besides being a hard to read these are horrible to maintain.

Do you think the code has a readability issue, and because of the readability issue, do you think it's hard to maintain?

In previous versions when one could use swagger the documentation was made from what was actually in the code.

What is the "previous versions" in your context? It originally started with using decorators from Day 1.

How long is it going to take before one of those is out of sync with the actual request parameters or response types.

If you frequently experience this kind of "out-of-sync" problem, do you think it's the extension's issue or your API design issue?

But for a normal sized site with multiple developers and 100s or more different methods being exposed.. This will just be one big mess.

I'm confused whether we're using the same term of "normal sized site" for an Azure Functions app. If your organisation puts 100s of devs to maintain one single Azure Function app, I'm really sorry that I feel the pain. But, for the case, I would really recommend re-architecting your application to split into 100s of Azure Functions apps, or use a monolithic app using ASP.NET Web API.

some type of roadmap where auto generation of the specifications is in the future (which I dearly hope)

I'm not sure what you really meant with this statement, but this extension is to auto-generate the OpenAPI document from the Azure Functions app.

Please make sure that this is an extension of Azure Functions core runtime, not the part of the core runtime. Therefore, if you find this extension doesn't offer much values that you expected, please drop using this extension. I'm pretty sure that you will find a better way to suit to your purpose.

[johnnyreilly]

Thanks for your considered response to a slightly hostile question @justinyoo

I wonder if I could ask a subquestion on the following?:

How long is it going to take before one of those is out of sync with the actual request parameters or response types.

Would it be possible to have some kind of mechanism that validates whether what an endpoint produces matches the decorators? I appreciate that getting 100% coverage of this might be tricky, but having some kind of mechanism in place which reduced the likelihood of things going out of alignment would offer a great deal of value. (spoiler: I've experienced things going out of alignment a number of times and I'm trying to find mitigation approaches)

@SyntaxWarrior the functionality you desire already exists in @vitalybibikov excellent https://github.com/vitalybibikov/AzureExtensions.Swashbuckle - maybe worth a look for your use cases

However, I'm not sure it supports .NET 6

[justinyoo]

Would it be possible to have some kind of mechanism that validates whether what an endpoint produces matches the decorators?

I don't have the answer for that. But what I've got in mind is that, if you use reflection and get the list of decorators, then it might be able to check what's declared and what's actually returned.

[johnnyreilly]

Yeah that's kind of what I was pondering. It would be amazing if it could be done at compile time, I suspect that would not be straightforward.

If there was a runtime mechanism with which it could be validated, it would be possible to make your app fail hard at startup and so prevent shipping a version of the app where swagger and the functions are out of alignment

[justinyoo]

Let's duscuss further. I'm also interested in this type of "linting" process. I don't think it's possible during the compile time, but it may be possible during the runtime (startup time).

[jackbatzner]

Let's duscuss further. I'm also interested in this type of "linting" process. I don't think it's possible during the compile time, but it may be possible during the runtime (startup time).

This could be done via a Roslyn Analyzer. I think the real answer is that it's hard to dive deep in code and truly understand wrapped responses.

[johnnyreilly]

Ooooh that sounds potentially exciting @jackbatzner !

[tommck]

I'm wondering if it would be possible to have less attributes.. possibly referencing something else so that you don't have just as many attribute lines as you have function code.

I find the attributes hard to parse, myself.

I wonder if we could have 1 attribute with a bunch of well named properties on it. That would allow for it to be more readable in my opinion

[jackbatzner]

I'm wondering if it would be possible to have less attributes.. possibly referencing something else so that you don't have just as many attribute lines as you have function code.

I find the attributes hard to parse, myself.

I wonder if we could have 1 attribute with a bunch of well named properties on it. That would allow for it to be more readable in my opinion

@tommck - Would you be able to give an example of what you're looking for?

[rockgecko-development]

Regarding auto detecting the response type from a function at compile time, it's not really possible, because both Azure Functions and the OAS spec allow for different response types for different http status codes or content-types (you can even respond to multiple http verbs in the same function). As mentioned, if you need this, you should look at ASP.NET Core Web API, which has a few more guardrails to do what you're asking for automatically.

Regarding ensuring the response type matches the spec at runtime, there are other existing projects that do this, for example Pact. This can generate a 'pact file' contract based on a OAS spec, and use it to call and compare against your running API.

[johnnyreilly]

Pact is great - but it's slightly tackling a different problem. The aim is to have a way to validate that the API matches the swagger / open API generated at runtime.

[rockgecko-development]

@johnnyreilly ah yes Pact doesn't do this directly, they suggest Schemathesis as one example. Here's a full example of using a dotnet core API to generate a OAS file, running it against schemathesis to verify the API endpoints and responses match the OAS, then using Pactflow to check it against the consumer pact version, before signalling to the build pipeline that it's safe to deploy.

[marcin-burak]

I personally develop a lot of small APIs surrounding Microsoft Graph and Power Platform and I'm really grateful that this OpenAPI extension exists. Now I can create my serverless API, generate my Typescript client using NSwag and integrate my front-end and back-end much faster. Going some time back, when I was forced to write my own Typescript contracts and keep URIs synced both on the back-end and the client was a maintenance nightmare - I will take decorators any day over going back to the old days.

[Sti2nd]

I think this is a good feature request. Why write documentation on the code when the compiler knows exactly which HTTP statuses can get returned!

To answer the question in the title, yes, we use this in production. And the uglyness can be solved, as this is the general problem of ugly code, which is the fault of the developer... unless you use a good formatter! The only good one I have found is CSharpier.