Hein.Swagger

NuGet Information

Hein.Swagger

<!-- if netcoreapp2.* use -->
<PackageReference Include="Hein.Swagger" Version="1.0.5" />

<!-- if netcoreapp3.* use -->
<PackageReference Include="Hein.Swagger" Version="3.0.0" />

Fun Repo to create an easier 'Swagger Gen' for api documentation

I wanted to create some helper/extensions/add on's to the awesomeness of SwaggerGen. I found it difficult to add/implement security keys, and other cool documentation to my api's swagger. (because I really didn't read the documentation, but who ever does 😉).

So, I added some extension methods to add to the SwaggerGenOptions to achieve what 'I' think should be called. I also added some Attributes/tags to add to your controllers, that will include/exclude from your swagger generation.

IMPORTANT! Major Version Update

1.0.5 => 2.0.2
With NetCore 3.1 being supported by AWS lambda now... I wanted to upgrade my apps to the new supported version. By doing so everything I've created for this swagger helper is obsolete... so had to so a major overhaul renaming some classes to make interfaces work and so forth.

Hein.Swagger	Swagger Versions	NetCore Versions
1.0.5	Swagger V2	netcoreapp2.*
3.0.0	Swagger V3	netcoreapp3.*

Cool Shiz!

• Adding a GitHub Repo Link
• Enforce API Keys
• Include/Exclude Controllers
• Group Controllers via Attribute
• Use Description and Summary Attributes
• Document Response Headers in Attributes
• API Versioning Documented in Swagger

---

Add Github Repository Url

There are times you want to marry up your github repository/code base with your live working app. So that developers can see your masterpiece. This extension will create an 'externalDocs' section in your swagger json, and will create a link in your UI.

Implementation:

services.AddSwaggerGen(x =>
{
   x.AddGithubRepository("https://github.com/brandonhein/Hein.Swagger");
}

---

Enforce API Keys

There are times you want to expose your Swagger documentation in a public fashion... but you also want to protect your API endpoints from the outside world. API keys work great for this! Swagger comes with some auto authorization setup, but it's tricky to leverage. This repository makes it easy with an extension to help you out!

Implementation:

services.AddSwaggerGen(x =>
{
   x.AddHeaderKey("apiKey", "Your Header Access Key");
   x.AddQueryKey("queryKey", "Your Query Access Key");
   x.AddCookieKey("cookieKey", "Your Cookie Access Key");
}

Bonus for AWS API Gateway enforcers
Implementation:

services.AddSwaggerGen(x =>
{
   x.EnforceAwsApiKey(); //this will enforce 'x-api-key' in the header
}

---

Include/Exclude Controllers and/or Actions from Swagger Gen

I recently deployed an application that served as both a UI and API... I wanted to document the API piece for the app, without having swagger generate documentation of the UI controllers and action. I honestly thought there was something more 'swagger' for an attribute to use other than ApiExplorerSettingsAttribute and setting the IgnoreApi boolean. So I added these attributes to 'swagger-ize' your code base up a bit more. Enjoy 😄

To tell Swagger Gen this controller can be swaggerized:

[Swagger]
public class SampleController : Controller
{ }

To tell Swagger Gen this controller should be excluded from being swaggerized:

[ExcludeFromSwagger]
public class ExcludeController : Controller
{ }

---

Group your Controllers with an Attribute!!!

I have an application that did location lookup... Each controller had a 'Route' that started with 'Lookup'... So I wanted to group them all together. I was amazed there's no good way to do this per the documentation. I saw here stackoverflow post, you have to use a an attribute tag on each method... thats stupid. So I figured out how to make it controller specific

Implementation:

services.AddSwaggerGen(x =>
{
   x.EnableControllerTags();
   //OR
   x.EnableAnnotations();
}

[SwaggerController("LookMom")]
public class SampleController : Controller
{ }

---

Description and Summary Attributes (so long xml comments)

When I saw I needed to include xml comments to help with description of my API's, I was appalled. I've already put all these attributes on my Actions... might as well keep it some what clean with more attributes. Inspired by Swashbuckle.AspNetCore.Annotations I did a similar. 😛

Implementation:

services.AddSwaggerGen(x =>
{
   x.EnableDescriptionTags();
   x.EnableSummaryTags();
   //OR
   x.EnableAnnotations();
}

[HttpPost]
[Consumes("application/json")]
[Produces("application/json")]
[ProducesResponseType(typeof(SampleModel), 200)]
[Description("Post Description")]
[Summary("Ope")]
public IActionResult Post([FromBody] SampleModel model)
{
   return Ok(model);
}

---

Document response headers in your swagger!

I had an endpoint where I was providing some an extension to the response body in the response headers. I couldn't find anywhere to add a ProducesHeader attribute anywhere to show case that this endpoint has a respone header that needs to be highlighted. You can now uses it in Attribute form like very thing else!

Implementation:

services.AddSwaggerGen(x =>
{
   x.EnableProducesHeaderTags();
   //OR
   x.EnableAnnotations();
}

[HttpPost]
[Produces("application/json")]
[ProducesHeader("x-collection-count", SwaggerType.Integer, "sample response header")]
[ProducesHeader("x-another-count", "another header attribute")]
[ProducesResponseType(typeof(SampleModel), 200)]
public IActionResult Post([FromBody] SampleModel model)
{
   return Ok(model);
}

---

API Versioning documented in swagger!

API Versioning allows you to route behavior between clients. SwaggerUI allows you to display multiple swagger docs. I'm a Controller Version guy. IE: A new Version gets all new/same controllers in a 'v{n}' folder, inside the controllers folder. This works if you create new routes (don't overwrite routes). While also managing the SwaggerVersion attribute on the controller.

Implementation:
In the ConfigureServices Method in startup:

services.AddSwaggerGen(x =>
{
   x.SwaggerDoc("v1", new Info {});
   x.SwaggerDoc("v2", new Info {});
   
   x.EnableSwaggerVersioning(); //tells Hein.Swagger to look at the SwaggerVersion attribute on controllers
}

In the Configure Method in startup:

app.UseSwagger();
app.UswSwaggerUI(c => 
{
   c.SwaggerEndpoint("/swagger/v1/swagger.json", "Hein.Swagger.Sample - v1");
   c.SwaggerEndpoint("/swagger/v2/swagger.json", "Hein.Swagger.Sample - v2");
});

Controllers:

[SwaggerVersion("v1")]
[Route("sample")]
public class SampleController : Controller
{
}

[SwaggerVersion("v2")]
[Route("v2/sample")]
public class SampleV2Controller : Controller
{
}

---