ASP.NET Core 2.2.0-preview1: Open API Analyzers & Conventions
What is it?
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. Visit https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1 to learn more about Open API Swagger and for details on configuring your applications to use it.
For 2.2, we’re investing in tooling and runtime experiences to 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?
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:
Open API documents contain each status code and response type an operation may return. In MVC, you use attributes such as
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.
Let’s look at the analyzer in action:
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.
If your controllers follows some common patterns, e.g. they are all primarily CRUD endpoints, and you aren’t already using
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
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
ApiConventionTypeattribute as an assembly level attribute. This applies the specified convention to all controllers in an assembly.
- Using the
ApiConventionTypeattribute on a controller.
ApiConventionMethod. This attributes accepts both the type and the convention method.
Like many other features in MVC, more specific attributes will supersede less specific ones. An API metadata attribute such as
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.
A convention is a static type with methods. These methods are annotated with
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
ProducesDefaultResponseType, two additional attributes –
ApiConventionTypeMatch – can be applied to the convention method that determines the methods they apply to.
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
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
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.
An easy way to get started authoring a custom convention is to start by copying the body of
DefaultApiConventions and modifying it. Here’s a link to the source of the type: https://raw.githubusercontent.com/aspnet/Mvc/release/2.2/src/Microsoft.AspNetCore.Mvc.Core/DefaultApiConventions.cs
This is one on our earliest forays in trying to use tooling to enhance runtime experiences. We’re interested in any thoughts you have about this as well as your experiences using this in your applications. The best place to provide feedback is by opening issues at https://github.com/aspnet/Mvc.
- See https://docs.microsoft.com/en-us/visualstudio/code-quality/use-roslyn-analyzers for help using analyzers.
- See https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1 for details on using Swagger with ASP.NET Core.