search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.63k stars 25.3k forks source link

Need help understanding how to describe my API for Visual Studio #25515

Open KSchlobohm opened 2 years ago

KSchlobohm commented 2 years ago

I want to build a Web API that has the metadata required for Visual Studio's connected service wizard (NSwagClient) to generate usable client code. Is there a doc that describes what attributes I should be using to describe my API?

As an example: It looks like API Conventions would be part of that recommendation, but I believe the RouteName of an [HttpGet] attribute will be used in the Swagger description as "operation name" which is used to describe the names of the methods generated by NSwagClient.

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

Rick-Anderson commented 2 years ago

@rafikiassumani-msft please review.

rafikiassumani-msft commented 2 years ago

@KSchlobohm Does the following learning module help? https://learn.microsoft.com/en-us/shows/beginners-series-to-web-apis/generating-api-clients-17-of-18--beginners-series-to-web-apis Also, the following doc has explanations on how to do this using NSwag. https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-nswag?view=aspnetcore-6.0&tabs=visual-studio.

We are exploring adding more options for client code generation for .NET8 (refit, Kiota). Let us know which specific metadata you are interested in for to document.

@captainsafia Any further thoughts on this?

KSchlobohm commented 2 years ago

Thanks @rafikiassumani-msft the video was good content and provided good guidance!

My goal was to have a generated client that uses intelligent method naming so I could more clearly associate the client methods with the service calls they were making.

If I remember correctly, I had previously found this doc but misunderstood it as how to configure my CLIENT, and not relevant to my SERVICE code. I read it more carefully this time and found that the doc provides more guidance with some hiccups.

  1. It looks like the doc has the old UseMvc() line in the Configure method which is not compatible with dotnet6 endpoint routing.

  2. By default the WeatherForecastController endpont is named Get so when you apply these changes it looks like nothing has happened. Readers that are new to NSwag (like me) might assume the route name of GetWeatherForecast would be applied when generating the client. It might be helpful for others to see the doc to show this by renaming the method name on the WeatherForecastController.

PS - Should the doc show the minimal API approach instead of talking about Configure and ConfigureServices methods?

captainsafia commented 2 years ago

It looks like the doc has the old UseMvc() line in the Configure method which is not compatible with dotnet6 endpoint routing.

UseMvc isn't exactly necessary here. As long as the NSwag services are configured in the app, you should be good to go.

By default the WeatherForecastController endpont is named Get so when you apply these changes it looks like nothing has happened. Readers that are new to NSwag (like me) might assume the route name of GetWeatherForecast would be applied when generating the client. It might be helpful for others to see the doc to show this by renaming the method name on the WeatherForecastController.

NSwag has a set of options for configuring the client. The best documentation for this is currently the NSwag wiki, although admittedly it's a little hard to grok. In particular, the generation of method names out of operation IDs is governed by the OperationNameGenerator. I believe you can configure these options via MSBuild by setting the values in the OpenApiReference property like so:

  <OpenApiReference Include="swagger.json" 
                    CodeGenerator="NSwagCSharp" Namespace="MyApp"
                    ClassName="MyEndpoints"
                    OutputPath="obj\Backend\MyAppClient.cs">
    <Options>/OperationNameGenerator:SingleClientFromOperationId</Options>
  </OpenApiReference>

You can try using the OpenApiOperationAttribute (ref) to explicitly set the ID, although NSwag should be pulling it from the name/

By the way, there was a bug that prevented the OpenApi tooling from generating OpenAPI documents for minimal APIs. You can find more information about it at https://github.com/dotnet/aspnetcore/issues/43391. It'll be fixed in 6.0.11 but just a heads up in case you run into it.

PS - Should the doc show the minimal API approach instead of talking about Configure and ConfigureServices methods?

Perhaps...it might be worthwhile to update all our docs for .NET 7 that use a Startup class to use the WebApplication model. For now, I think it's fine for these because the highlights emphasize the required service registrations.