swagger

In my most recent Pluralsight course, I spent some time talking about using Swashbuckle to create documentation for ASP.NET Core WebAPI applications. Swashbuckle is the .NET Core implementation of the OpenAPI Specification aka Swagger, but there are many other open source tools too for other languages. The demo project built was a simple "traditional" ASP.NET Core API that generated a "Superhero Name" based on a FirstName and LastName passed to the GET method. The old API architecture The architecture would not surprise anyone who has seen an MVC structure for ASP.NET Web API projects, except the .NET Core portions. Controllers, Views, Startup.cs, etc., published to an Azure AppService running on IIS. If this were a node....

One option for enabling the Swagger-UI capabilities is to direct the consumers of the api to http://petstore.swagger.io and have them put the url in the box at the top of the page. That's professional right? :-/ Alternatively, you can add the url of the service to the end with ?url= such as http://petstore.swagger.io?url=https://yoursite.azurewebsites.net/docs/swagger.json, but again probably not the best option. Here we can take advantage of Docker here and use the swaggerapi/swagger-ui Docker image and set some ENV variables within an Azure AppService Web Application and accomplish our own SwaggerUI. Creating a new AppService (Linux) Here we will use the Azure CLI to create our...

In my post Testing Azure Functions with Postman and Swagger I showed how to use the API Specification capabilities in Azure Functions and then take the endpoint url and test the API using Postman. Notice the url that is provided for the API. It isn't human readable, nor something I could rattle off to another developer over the phone or easy re-type. Creating a proxy A feature in Azure Function is proxies. Using this feature we can establish a new proxy for our function to point a "nice" url to the "no-so-friendly" API Definition. Now you can share the shorter more reasonable url, even use the test Swagger UI at http://petstore.swagger.io. Be sure to add http://petstore....

A new feature (preview) in Azure Functions is API Definition. This feature allows you to use the OpenAPI specification (aka Swagger) to document the functionality of your functions and/or endpoints. Checkout John Papa & I talk about using Swagger for ASP.NET Core on Pluralsight in Play by Play - Understanding API Functionality Through Swagger The documentation and a walkthrough of Creating OpenAPI 2.0 (Swagger) Metadata for a Function App (Preview) are available on docs.microsoft.com. Testing your function After you have your api defined, copy the endpoint in the API Definition URL box to use to import into Postman. Open Postman, click the Import button. Select Import from Link and paste your definition endpoint. Postman reads...

See GitHub Issue #795 for the details and discussion. One of the undocumented changes of converting from project.json to csproj, was the <DocumentationFile> no longer automatically copied to the output folder during the build or publish process. There have been multiple solutions, both pre and post publish scripts. However, understanding how MSBUILD works and finding the simplest way is key. Thanks to Eric Erhardt's latest comment here I think that this is the cleanest way. Add the following snippet to the .csproj to enable the copy of the documentation file to the output folder. It supports the F5 options as well as the dotnet build / dotnet publish CLI commands. Another important option tested was the ability to...