Open API (Swagger) Analyzers & Conventions in ASP.NET Core 2.2

No comments

Open API

Open API (alternatively known as Swagger) is a language-agnostic specification for describing REST APIs. The Open API ecosystem has tools that allows for discovering, testing and producing client code using the specification. Support for generating and visualizing Open API documents in ASP.NET Core MVC is provided via community driven projects such as NSwag, and Swashbuckle.AspNetCore.

For 2.2, they’re investing in tooling and runtime experiences to allow developers to produce better Open API documents. This work ties in with ongoing work to perform client code SDK generation during build.

How to use it?

Analyzer

For 2.2, we’re introducing a new API-specific analyzers NuGet package – Microsoft.AspNetCore.Mvc.Api.Analyzers. These analyzers work with controllers annotated with ApiController introduced in 2.1, while building on API conventions that we’re also introducing in this release. To start using this, install the package:


<PackageReference Include="Microsoft.AspNetCore.Mvc.Api.Analyzers"
    Version="2.2.0-preview1-35029"
    PrivateAssets="All" />

Open API documents contain each status code and response type an operation may return. In MVC, you use attributes such as ProducesResponseType and Produces to document these. The analyzer inspects controllers annotated with ApiController and identifies actions that do not entirely document their responses. You should see this as warnings (squiggly lines) highlighting return types that aren’t documented as well as warnings in the output. In Visual Studio, this should additionally appear under the “Warnings” tab in the “Error List” dialog. You now have the opportunity to address these warnings using code fixes.

The analyzer identified that the action returned a 404 but did not document it using a ProducesResponseTypeAttribute. We used a code fix to document this. The added attributes would now become available for Swagger / Open API tools to consume. It’s a great way to identify areas of your application that are lacking swagger documentation and correct it.

Conventions

If your controllers follows some common patterns, e.g. they are all primarily CRUD endpoints, and you aren’t already using ProducesResponseType or Produces to document them, you could consider using API conventions. Conventions let you define the most common “conventional” return types and status codes that you return from your action, and apply them to individual actions or controllers, or all controllers in an assembly. Conventions are a substitute to decorating individual actions with ProducesResponseType attributes.

By default, ASP.NET Core MVC 2.2 ships with a set of default conventions – DefaultApiConventions – that’s based on the controller that ASP.NET Core scaffolds. If your actions follow the pattern that scaffolding produces, you should be successful using the default conventions.

At runtime, ApiExplorer understand conventions. ApiExplorer is MVC’s abstraction to communicate with Open API document generators. Attributes from the applied convention get associated with an action and will be included in action’s Swagger documentation. API analyzers also understand conventions. If your action is unconventional i.e. it returns a status code that is not documented by the applied convention, it will produce a warning, encouraging you to document it.

There are 3 ways to apply a convention to a controller action:

  • Applying the ApiConventionType attribute as an assembly level attribute. This applies the specified convention to all controllers in an assembly.
[assembly: ApiConventionType(typeof(DefaultApiConventions))]
  • Using the ApiConventionType attribute on a controller.
[ApiConventionType(typeof(DefaultApiConventions))]
[ApiController]
[Route("/api/[controller]")]
public class PetsController : ControllerBase
{
    ...
}
  • Using ApiConventionMethod. This attributes accepts both the type and the convention method.
// PUT: api/Pets/5
[ApiConventionMethod(typeof(DefaultApiConventions), nameof(DefaultApiConventions.Put))]
[HttpPut("{id}")]
public async Task<ActionResult<Pet>> PutPet(long id, Pet pet)
{
    ...
}

Like many other features in MVC, more specific attributes will supersede less specific ones. An API metadata attribute such as ProducesResponseType or Produces applied to an action will stop applying any convention atributes. The ApiConventionMethod will supersede a ApiConventionType attribute applied to the method’s controller or the assembly; and an ApiConventionType attribute applied to a controller will supersede ones applied to the assembly.

Authoring conventions

A convention is a static type with methods. These methods are annotated with ProducesResponseType or ProducesDefaultResponseType attributes.

public static class MyAppConventions
{
    [ProducesResponseType(200)]
    [ProducesResponseType(404)]
    public static void Find(int id)
    {

    }
}

Applying this convention to an assembly would result in the convention method applying to any action with the name Find and having exactly one parameter named id, as long as they do not have other more specific metadata attributes.

In addition to ProducesResponseType and ProducesDefaultResponseType, two additional attributes – ApiConventionNameMatchand ApiConventionTypeMatch – can be applied to the convention method that determines the methods they apply to.

[ProducesResponseType(200)]
[ProducesResponseType(404)]
[ApiConventionNameMatch(ApiConventionNameMatchBehavior.Prefix)]
public static void Find(
    [ApiConventionNameMatch(ApiConventionNameMatchBehavior.Suffix)]
    int id)
{ }

The ApiConventionNameMatchBehavior.Prefix applied to the method, indicates that the convention can match any action as long as it starts with the prefix “Find”. This will include methods such as Find, FindPet or FindById. The ApiConventionNameMatchBehavior.Suffix applied to the parameter, indicates that the convention can match methods with exactly one parameter that terminate in the suffix id. This will include parameters such as id, or petId. ApiConventionTypeMatch can be similarly applied to types to constrain the type of the parameter. A params[] arguments can be used to indicate remaining parameters that do not need not be explicitly matched.

ASPHostPortal Fully Supports The Lastest ASP.NET Version

All of their servers run the latest versions of ASP.NET so they will always be able to support your site. Finally, the long awaited release of ASP.NET Core 2.2, ASPHostPortal are happy to announce the availability of the .NET Framework Core 2.2 for all their hosting packages.

ASPHostPortal Never Lose Your Data

Your data is safe. They have deployed the latest cloud infrastructures and use only premium hardware components, including fully redundant primary and backup storage devices those are RAID protected. This means that your data has triple redundant, it is not just copied and it is always available. If you want to roll back, access an accidentally deleted file, or need a complete restore, they have you covered.

ASPHostPortal’s Expert Support Team

Everything starts with impeccable support. The unmatched knowledge, experience, and dedication of their team truly make them stand out. They understand that people are the most important piece of the service they provide, and that is why they are at the top of the list. You’ll notice the difference the first time you talk to one of their ASP.NET experts.

ASPHostPortal’s World Class Data Center

Their data centers are strategically located around the country to provide their customers with the highest levels of availability, service and support on the market. Their data centers located on US (Washington & Seattle), Netherlands (Amsterdam), Singapore, Hong Kong, United Kingdom (London), Australia (Melbourne), France (Paris), Germany (Frankfurt), Italy (Milan), India (Mumbai). Each Data Center is custom designed with raised floors. Each Data Center is equipped with HVAC temperature control systems with separate cooling zones, seismically braced racks, advanced early smoke detection and fire suppression systems. Their Data Centers are supported by some of the most powerful physical security in the business. They have 24/7 video surveillance, security breach alarms and Biometric thumb print scanners at every entryway.

ASPHostPortal Offers Affordable Price

ASPHostPortal offers affordable price for all of ASP.NET Core 2.2 hosting plans. Customers can start their ASP.NET Core 2.2 site just from $1.00/mo. They are so confident that you will like their service, so they brave to offer a 30 day money back guarantee on hosting fees. Just cancel before 30 days, and they will refund your entire hosting fee. You can get cheaper price with their hosting promotion and free add-ons too, for more information just visits their official site at http://asphostportal.com.



4.2/5 - (8 votes)