Whether APIs are<\/em> your product, or they’re a facet of the topology you build by default in your daily consulting work or freelancing, the process of building, testing, and integrating APIs can appear daunting. The posts in this series will show you how .NET is a great choice, as it offers RESTful, serverless, and more modern gRPC and HTTP2\/3 investments. By the end, you’ll know some new techniques and conventions, and have some sample code and open-source projects to follow.<\/p>\n If you’ve ever referenced a SOAP Web Service within Visual Studio using right-click Add Web Reference<\/strong> or, once WCF appeared, Add Service Reference<\/strong>, you know the joy brought to your development experience by the tools and their support for a standard description format – the Web Service Definition Language (WSDL).<\/p>\n The OpenAPI Specification has evolved as the leading industry convention for describing standard request\/response HTTP APIs, and a myriad of tools, open-source packages, and frameworks have been built atop ASP.NET Web API to make the process of building HTTP APIs simple. Whilst OpenAPI isn’t as strict or verbose as WSDL, the relaxed nature of the language makes for a wide variety of misuses and missed opportunities.<\/p>\n The .NET community is still rich with an ecosystem of open-source packages and tools, some of which we use in the ASP.NET templates and Visual Studio tooling. In the ASP.NET Core 5 Web API space, there are a handful of packages developers can use to get going with an end-to-end development experience using OpenAPI specifications as a contract between the API and the clients:<\/p>\n A well designed API is so much nicer to develop, maintain, and consume. By following a few simple conventions when building Web APIs that use these packages to describe your APIs, your APIs will be much<\/strong> more discoverable, integrate with other products and cloud services more easily, and in general, offer more usage scenarios.<\/p>\n This post will use a sample Visual Studio Solution<\/a>. In the solution you’ll find a simple Web API project for Contoso Online Orders. We’ll build more onto the API over time, but just to give you a glimpse at the API’s shape, take a look at the Swagger UI page from the Web API project’s Debug experience.<\/p>\n The solution comes with the API non-optimized for discoverability. Throughout the steps in this post, you’ll be shown how to use any of the Visual Studio family of IDEs to make changes to the projects so you’ll see a before-and-after experience of the API as it was at first, then improved over time by small incremental changes.<\/p>\n The changes we’ll make can be summarized as:<\/p>\n With that, we’ll jump right in and see how some of the attributes built in to ASP.NET Core 5 Web API can make your APIs concise, right out of the box.<\/p>\n The JSON code for the Web API project is, by default, rather verbose and, ironically, not very informative about what could happen when the API is called in various states. Take this ProducesAttribute<\/a> is used to specify the content type of the output that will be sent by the API, and the corresponding ConsumesAttribute<\/a> is used to specify the request content types the API expects to receive. As described in the docs on formatting Web API output<\/a>, As shown in the sample project<\/a> corresponding to this blog series, you can also use the MediaTypeName<\/a> class to make it simpler to use well-known values for the media type. With the sample controllers, we want every request object and response object to be serialized as JSON. To facilitate this at the controller level, each controller is decorated with both the Since the code in the sample project is built to check for certain symbles using compiler directives, you can easily tweak the build configuration to include the Defined Constant value of Now, when the Web API project is re-built and run, the OpenAPI specification is considerably smaller, due in large part to the removal of the unnecessary request and response content nodes. The updated JSON, reflecting this change, now only shows the Web API developers can make use of a variety of Action Result inheritors to send the appropriate HTTP status code to the calling client in addition to the object or operation implemented by the API. In the However, the OpenAPI JSON for this method only shows the 200 response code, the default behavior for an HTTP GET. OpenAPI supports the notion of communicating all potential response codes an API could return, so we’re missing out on an opportunity to inform potential consumers or code generators on “what could happen” when the API method is called.<\/p>\n Web API conventions, available in ASP.NET Core 2.2 and later,include a way to extract common API documentation and apply it to multiple actions, controllers, or all controllers within an assembly. Web API conventions are a substitute for decorating individual actions with [ProducesResponseType]. Since API Conventions are extensible, you could write your own to enforce more granular rules if needed. Common use cases of conventions would be to:<\/p>\n The sample Web API project’s For this second compiler change, here’s how to do the same thing in Visual Studio. You can also double-click any Once you’ve made the change, re-building and running the Web API project will result with the OpenAPI specification being equipped with response code details for each of the API operations.<\/p>\n In the OpenAPI specification<\/a>, Whilst the Take a look at a condensed version of the OpenAPI specification. This snapshot summarizes the API to the various endpoints, verbs, and operations offered by the API.<\/p>\n Each of the Web API Action Methods in the sample project is decorated with two variations of the Attribute Route. The first, wrapped in the The 3rd and final compiler switch you’ll add to the sample project activates Once the Human readability isn’t the only benefit. Code generators like the Microsoft.dotnet-openapi<\/a> tools, NSwag<\/a>, and AutoRest<\/a> operate more gracefully when OpenAPI specifications include the Thinking design-first<\/h2>\n
\n
The sample project<\/h2>\n
![\"Swagger](\"https:\/\/devblogs.microsoft.com\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/swagger-ui.png\")
<\/p>\n\n
Produces \/ Consumes<\/h2>\n
orders<\/code> operation, shown here. The C# code in my Web API controller will always output objects serialized in JSON format, but the OpenAPI specification is advertising other content types, too.<\/p>\n{\r\n \"paths\": {\r\n \"\/orders\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ],\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"Success\",\r\n \"content\": {\r\n \"text\/plain\": {\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"$ref\": \"#\/components\/schemas\/Order\"\r\n }\r\n }\r\n },\r\n \"application\/json\": {\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"$ref\": \"#\/components\/schemas\/Order\"\r\n }\r\n }\r\n },\r\n \"text\/json\": {\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"$ref\": \"#\/components\/schemas\/Order\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nProduces<\/code> and Consumes<\/code> filters by either specifying the content-type you want to output:<\/p>\n[Produces(\"application\/json\")]\r\n[Consumes(\"application\/json\")]\r\n<\/code><\/pre>\nProduces<\/code> and Consumes<\/code> attributes. To each attribute is passed the well-known property MediaTypeNames.Application.Json<\/code>, thus specifying that the only content type our API should use for both directions is application\/json<\/code>.<\/p>\n [Route(\"[controller]\")]\r\n [ApiController]\r\n#if ProducesConsumes\r\n [Produces(MediaTypeNames.Application.Json)]\r\n [Consumes(MediaTypeNames.Application.Json)]\r\n#endif\r\n public class AdminController : ControllerBase\r\n {\r\n \/\/ controller code\r\n }\r\n<\/code><\/pre>\nProducesConsumes<\/code> to turn on the attributes in the Web API sample project code. In Visual Studio for Mac, constants can be added by double-clicking a .csproj<\/code> file in the Solution Explorer to open the project properties window<\/a>.<\/p>\n![\"Adding](\"https:\/\/devblogs.microsoft.com\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/produces-consumes.png\")
<\/p>\napplication\/json<\/code> content type, thus making the API specification much more compact.<\/p>\n{\r\n \"paths\": {\r\n \"\/orders\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ],\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"Success\",\r\n \"content\": {\r\n \"application\/json\": {\r\n \"schema\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"$ref\": \"#\/components\/schemas\/Order\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nHTTP Response Codes<\/h2>\n
GetProduct<\/code> method, for example, the code tries to get a product by ID. If the product is found, it is returned along with an HTTP OK via the Ok<\/code> result. If the product isn’t found, the API returns an HTTP 404, with no payload.<\/p>\n[HttpGet(\"\/products\/{id}\")]\r\npublic async Task<ActionResult<Product>> GetProduct(int id)\r\n{\r\n var product = StoreServices.GetProduct(id);\r\n\r\n if(product == null)\r\n {\r\n return NotFound();\r\n }\r\n else\r\n {\r\n return Ok(product);\r\n }\r\n}\r\n<\/code><\/pre>\n\"\/products\/{id}\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Shop\"\r\n ],\r\n \"parameters\": [\r\n {\r\n \"name\": \"id\",\r\n \"in\": \"path\",\r\n \"required\": true,\r\n \"schema\": {\r\n \"type\": \"integer\",\r\n \"format\": \"int32\"\r\n }\r\n }\r\n ],\r\n \"responses\": {\r\n \"200\": {\r\n \"description\": \"Success\",\r\n \"content\": {\r\n \"application\/json\": {\r\n \"schema\": {\r\n \"$ref\": \"#\/components\/schemas\/Product\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nWeb API Conventions<\/h2>\n
\n
Program.cs<\/code> file is decorated with the API Convention attribute – this is an approach that will impact the output of every Web API controller in the assembly, but you can apply conventions more granularly if desired. See the documentation<\/a> on Web API conventions for more details.<\/p>\nusing Microsoft.AspNetCore.Hosting;\r\nusing Microsoft.Extensions.Hosting;\r\n\r\n#if ApiConventions\r\n[assembly: ApiConventionType(typeof(DefaultApiConventions))]\r\n#endif\r\n\r\nnamespace ContosoOnlineOrders.Api\r\n{\r\n public class Program\r\n {\r\n<\/code><\/pre>\n.csproj<\/code> file in the Solution Explorer and manually enter it (see below).<\/p>\n\n
![\"Add](\"https:\/\/devblogs.microsoft.com\/aspnet\/wp-content\/uploads\/sites\/16\/2021\/02\/api-conventions.png\")
<\/p>\n<\/blockquote>\n\"\/products\/{id}\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Shop\"\r\n ],\r\n \"parameters\": [\r\n {\r\n \"name\": \"id\",\r\n \"in\": \"path\",\r\n \"required\": true,\r\n \"schema\": {\r\n \"type\": \"integer\",\r\n \"format\": \"int32\"\r\n }\r\n }\r\n ],\r\n \"responses\": {\r\n \"404\": {\r\n \"description\": \"Not Found\",\r\n \"content\": {\r\n \"application\/json\": {\r\n \"schema\": {\r\n \"$ref\": \"#\/components\/schemas\/ProblemDetails\"\r\n }\r\n }\r\n }\r\n },\r\n \"default\": {\r\n \"description\": \"Error\",\r\n \"content\": {\r\n \"application\/json\": {\r\n \"schema\": {\r\n \"$ref\": \"#\/components\/schemas\/ProblemDetails\"\r\n }\r\n }\r\n }\r\n },\r\n \"200\": {\r\n \"description\": \"Success\",\r\n \"content\": {\r\n \"application\/json\": {\r\n \"schema\": {\r\n \"$ref\": \"#\/components\/schemas\/Product\"\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nEmit OpenAPIs operationId in Web API<\/h2>\n
operationId<\/code> is defined as “an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.” The operationId<\/code> attribute is used essentially to provide a explicit string-based identifier for each operation in an API.<\/p>\noperationId<\/code> attribute isn’t required according to the OpenAPI Specification, including it in your APIs offers significant improvements in the API Consumption<\/strong> experience – documentation, code-generation, and integration with a myriad of services.<\/p>\n{\r\n \"paths\": {\r\n \"\/orders\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ]\r\n },\r\n \"post\": {\r\n \"tags\": [\r\n \"Shop\"\r\n ]\r\n }\r\n },\r\n \"\/orders\/{id}\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ]\r\n }\r\n },\r\n \"\/products\/{id}\/checkInventory\": {\r\n \"put\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ]\r\n }\r\n },\r\n \"\/products\": {\r\n \"post\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ]\r\n },\r\n \"get\": {\r\n \"tags\": [\r\n \"Shop\"\r\n ]\r\n }\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nOperationId<\/code> compiler symbol, results in the name of the C# Action Method being automatically set as the operationId<\/code> value. The Name<\/code> property, when passed to the constructor of each HTTP verb filter, is used as the value of the operationId<\/code> attribute in the generated OpenAPI specification document. The second lacks the Name<\/code> property, which results in the operationId<\/code> attribute value being omitted.<\/p>\n#if OperationId\r\n[HttpGet(\"\/orders\", Name = nameof(GetOrders))]\r\n#else\r\n[HttpGet(\"\/orders\")]\r\n#endif\r\npublic async Task<ActionResult<IEnumerable<Order>>> GetOrders()\r\n{\r\n return Ok(StoreServices.GetOrders());\r\n}\r\n\r\n\r\n#if OperationId\r\n[HttpPost(\"\/orders\", Name = nameof(CreateOrder))]\r\n#else\r\n[HttpPost(\"\/orders\")]\r\n#endif\r\npublic async Task<ActionResult<Order>> CreateOrder(Order order)\r\n{\r\n try\r\n {\r\n StoreServices.CreateOrder(order);\r\n return Created($\"\/orders\/{order.Id}\", order);\r\n }\r\n catch\r\n {\r\n return Conflict();\r\n }\r\n}\r\n<\/code><\/pre>\noperationId<\/code> generation. If you’re using Visual Studio for Mac or Windows, use one of the techniques shown earlier to set it. Or, if you’re in Visual Studio Code or another text editor, just edit the .csproj<\/code> files in the solution (both of them) to include the operationId<\/code> value (and to expect it during consumption and code-generation).<\/p>\n<PropertyGroup Condition=\" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' \">\r\n <DefineConstants>TRACE;DEBUG;NET;NET5_0;NETCOREAPP;ProducesConsumes;ApiConventions;OperationId<\/DefineConstants>\r\n<\/PropertyGroup>\r\n<\/code><\/pre>\nOperationId<\/code> symbol is set, the Action Methods on each of the Web API controllers emits operationId<\/code> attribute values. Considering the condensed version of the OpenAPI specification from earlier, here’s the new OpenAPI spec inclusive with the operationId<\/code> attributes.<\/p>\n{\r\n \"paths\": {\r\n \"\/orders\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ],\r\n \"operationId\": \"GetOrders\"\r\n },\r\n \"post\": {\r\n \"tags\": [\r\n \"Shop\"\r\n ],\r\n \"operationId\": \"CreateOrder\"\r\n }\r\n },\r\n \"\/orders\/{id}\": {\r\n \"get\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ],\r\n \"operationId\": \"GetOrder\"\r\n }\r\n },\r\n \"\/products\/{id}\/checkInventory\": {\r\n \"put\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ],\r\n \"operationId\": \"CheckInventory\"\r\n }\r\n },\r\n \"\/products\": {\r\n \"post\": {\r\n \"tags\": [\r\n \"Admin\"\r\n ],\r\n \"operationId\": \"CreateProduct\"\r\n },\r\n \"get\": {\r\n \"tags\": [\r\n \"Shop\"\r\n ],\r\n \"operationId\": \"GetProducts\"\r\n }\r\n }\r\n }\r\n}\r\n<\/code><\/pre>\nBenefits in the Generated SDK Code<\/h3>\n
operationId<\/code> attribute.<\/p>\n