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?

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.

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.

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: ApiConvention(typeof(DefaultApiConventions))]

• Using the ApiConventionType attribute on a controller.

[ApiConvention(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 – ApiConventionNameMatch and 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.

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

Feedback

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.

Additional help

Shenmue I & II is Now Available on Steam!

SEGA®’s most requested re-release of all time finally comes to a new generation. Shenmue delivers an epic story of revenge within a unique open world that is still unrivalled in depth and detail. Return to the epic saga that defined modern gaming. The saga begins…again.

“I have the benefit of working for a lot of different indie devs, so I notice patterns that a developer who’s only putting out their one game wouldn’t seeAU.”

– Emily Morganti speaking to Kotaku about key scammers trying to take advantage of independent developers.

Before a game is launched, it’s likely that a strange email address requesting a free copy for review purposes will show up in the inbox of an unsuspecting indie dev.

Key scammers utilize this method constantly, and it’s no secret that it’s an issue within the industry. 

In a recent interview with Kotaku, Emily Morganti, who handles PR for adventure games, discusses how key scammers continue to be a problem for indie devs trying to market their titles without being conned.

Morganti explains the subtleties that lie in every odd request, which takes the form of misleading email addresses and copy that seems off.  

“Some of these people email about every game that comes out, using the same copy-and-paste email. Some people do a blanket request for multiple games on the same day—so multiple developers are getting the exact same email about how excited someone is to stream their game,” she explains.

“There was one guy a few years ago with a long sob story about how he’d lost his job and had a big tax bill to pay and couldn’t afford games but a free copy of [insert game name here] would make his life complete.”

Despite sharing a few similarities, every scammer works differently when it comes to execution. The last notable scammer Morganti encountered made waves, as he reached out to many devs for free codes.

Going by the name Dmitry Tseptsov, he sent several emails to Morganti asking for codes, explaining that he operated a coffee shop in Ukraine where he’d give out video games as prizes for trivia. Unsurprisingly, the request turned out to be a ploy for free codes despite the cafe being a legitimate business. 

Morganti admits that its becoming difficult to parse which review requests are honest and which ones are malicious. She recalls an instance where an editor for a publication reached out for a code the same time a scammer (who was impersonating the editor) did as well.

“I heard from the editor first and added him to my list for a review copy, and then I heard from the scammer on the day we got keys, and I sent it to him thinking it was the same person,” she says. “A few days after that, the real editor emailed me to ask where his key was, and we pieced it together.”

“I’ve been doing PR since 2006 and always had a policy of sending a key to anyone who asked for one, no matter how small the site, but I’m a lot more suspicious now,” Morganti continues.

“The work involved in vetting people to figure out if they’re legit or not isn’t worth the effort and I think writers from smaller sites and freelancers are paying the price.”

She was speaking as part of a longer discussion around scammers trying to take advantage of independent developers and how it affects smaller contet creators, so be sure to read the entire piece over at Kotaku.

Cosmoscope, the studio behind Switch newcomer Morphies Law, has submitted a patch to Nintendo in order to fix some of the issues experienced by early players.

If you missed the news, Morphies Law recently ‘did a Fortnite‘, surprising everyone by launching on the system without any real warning; the game was shown off during the 2018 Indies Showcase, and was available on the console just hours later.

The premise is incredibly creative, and the game offers up an interesting twist on the shooter genre with its changing body mass mechanic. Players have noticed some frustrating issues early on, however – a fact that we confirmed in our review.

If you’ve been playing the game and faced the odd issue or two, here are the full patch notes currently under review by Nintendo. Assuming it’s approved, these changes should soon be implemented to improve the game’s performance:

– Changed online settings to enforce geographical proximity – this should alleviate the lag while we continue working on setting up dedicated servers, please let us know your feedback.
– Fixed spawn protection – now you’ll be invincible for 5 seconds or until you leave your base.
– Fixed gunshot sounds looping infinitely sometimes on death.
– Fixed loud sounds that would sometimes play before the map intro.
– Fixed XP gains for private games – it is now 75% of the regular online XP instead of 25%.
– Increased the daily cap on XP and Nuts that can be gained from offline/private/local games to 5000XP and 500Nuts.
– Fixed bug in Tanker Town where exiting tunnels at certain inclinations would sometimes kill you.
– Fixed the recharge time of weapon part “Sonic Punch” – it is no longer spammable.
– Disabled the ability to “unready” in private/LAN matches to avoid potential 5v3 scenarios.

Did you grab a copy of the game on day one? How have you found the experience? Let us know how you’ve been getting on in the comments below.

Phantom Doctrine is Now Available on Steam and is 10% off!*

The year is 1983. The world teeters on the verge of destruction as the Cold War tightens its icy grip. East or West: trust no one, question everything. The fate of humanity rests in your hands as you pit spy versus spy in tactical Phantom Doctrine.

*Offer ends August 21 at 10AM Pacific Time