Skip to content

OpenAPI Document Converters for Visual Studio 2017

Howard van Rooijen By Howard van Rooijen Co-Founder
OpenAPI Document Converters for Visual Studio 2017

In my previous post I documented a technical spike I carried out to see how I could take the OpenAPI.NET SDK and create a Custom Tool in Visual Studio, in particular a Single-File Generator, that could be used to improve the Azure Functions v1 local development experience. Since then the OpenAPI.NET SDK reached v1.0 and while I was at BUILD I decided to spent a little bit more time productionising the solution. I've migrated the solution to its own GitHub repo - Endjin.OpenAPI.Converters, fixed issues around supporting the new Common Project System, and changed the Custom Tool names to make a bit more sense:

  • to OpenAPI 2.0 JSON - Set Custom Tool to "ConvertToOpenApi_2_0_Json"
  • to OpenAPI 2.0 YAML - Set Custom Tool to "ConvertToOpenApi_2_0_Yaml"
  • to OpenAPI 3.0 JSON - Set Custom Tool to "ConvertToOpenApi_3_0_Json"
  • to OpenAPI 3.0 YAML - Set Custom Tool to "ConvertToOpenApi_3_0_Yaml"

The primary usage scenario for this tool is the authoring of OpenAPI files in local Azure Function (V1) projects in the easier to maintain YAML format and automatically generating the required swagger.json file.

To add a OpenAPI document to your Function v1 project add the following folder structure

Azure Weekly is a summary of the week's top Microsoft Azure news from AI to Availability Zones. Keep on top of all the latest Azure developments!

.azurefunctions\swagger\

Add a new file called swagger.yaml. On the property pane for this file, set the Custom Tool to equal "ConvertToOpenApi_2_0_Json". This will generate a swagger.json file.

Make sure you set the Build Action to "Content" and Copy to Output Directory to "Copy if newer" for the newly generated swagger.json file.

The best hour you can spend to refine your own data strategy and leverage the latest capabilities on Azure to accelerate your road map.

I've packaged up the extension into an easily installable VSIX package that can be downloaded from the releases tab on the GitHub repo. Please try it out and leave any feedback / issues on GitHub.

Special Thanks

Useful Resources

FAQs

What is the primary usage scenario for the OpenAPI document converters? Authoring OpenAPI files in local Azure Function V1 projects using the easier to maintain YAML format while automatically generating the required swagger.json file. Add a swagger.yaml file in the .azurefunctions/swagger/ folder, set the Custom Tool to ConvertToOpenApi_2_0_Json, and the JSON file is generated automatically.
What were the key improvements in this productionised version? Migration to a dedicated GitHub repo (Endjin.OpenAPI.Converters), fixes for Common Project System support, and renamed Custom Tools for clarity: ConvertToOpenApi_2_0_Json, ConvertToOpenApi_2_0_Yaml, ConvertToOpenApi_3_0_Json, and ConvertToOpenApi_3_0_Yaml. The extension is packaged as an easily installable VSIX.

Also worth reading:

Json Schema Patterns in .NET - Data Object

Json Schema Patterns in .NET - Data Object

Matthew Adams

Define a simple data object in JSON Schema and generate strongly typed C# with Corvus.JsonSchema, complete with properties, implicit conversions, and zero-allocation serialization.
Json Schema Patterns in .NET - Mapping input and output values

Json Schema Patterns in .NET - Mapping input and output values

Matthew Adams

Convert between unrelated IJsonValue types across API, CRM, and database schemas with near-zero allocation. A schema-first alternative to AutoMapper for JSON-driven .NET applications.
OpenAPI code generators for Visual Studio

OpenAPI code generators for Visual Studio

Howard van Rooijen

Using the recently Open Sourced OpenAPI SDK, we create a Visual Studio extension from converting OpenAPI specificaitons between YAML and JSON formats.

Howard van Rooijen

Co-Founder

Howard van Rooijen

Howard spent 10 years as a technology consultant helping some of the UK's best known organisations work smarter, before founding endjin in 2010. He's a Microsoft ScaleUp Mentor, and a Microsoft MVP for Azure and Developer Technologies, and helps small teams achieve big things using data, AI and Microsoft Azure.