Skip to content

An opinionated ASP.NET Core 2.2 Web API template for new web applications.

License

Notifications You must be signed in to change notification settings

Homely/Homely.AspNetCore.WebApi.Template

Repository files navigation

Homely - ASP.NET Core MVC Helpers

Homely - ASP.NET Core WebApi Template.

This library contains an opinionated templated ASP.NET Core WebApi project. The template package is available on NuGet, which will allow new API's/microservices to be easily created via the CLI (command line interface) dotnet new tool/command.

This library heavily leverages our other helpers library.

Build status


How to use

  1. Install the template using the command line (we do this once, only):
dotnet new -i Homely.AspNetCore.WebApi.Template
  1. Create a new project using the template (we do this every time we're creating a new web api):
dotnet new homelyapi -n YourOrg.YourServiceName.WebApi 

Optional settings:

Argument Description Default Value Sample Value
swagger-title Title for the Docs "My API" "Awesome API"
swagger-version API Version v1 v2
swagger-routeprefix Root route to access the swagger docs "swagger" "accounts/swagger "

The new API template will be created with the namespace specified in the -n parameter.

How it works

  • The template.json file configures how the template will be created.
  • Note the sourceName property in that file with the value Homely.ProjectName.WebApi. This is the default namespace for all the .cs files, which is replaced by the value in the -n parameter.
  • The nuspec dictates this package is a special "template" file, via the <packageType name="Template"> directive. More info about templates: https://docs.microsoft.com/en-us/dotnet/core/tools/custom-templates

Current default features

  • Based off an Empty ASPNET Core 2.2 Web App.
  • Uses ProblemDetails for consistent error models [Shoutout to @khellang Middleware library]
  • Default HomeController with default route "/". (You can optionally provide a nice text message / banner :) )
  • Common JSON settings. (e.g. Camel casing, indenting, etc.)
  • Serilog for logging (Development mode logs to Console). Check here to use other sinks.
  • Swagger and SwaggerUI (via Swashbuckle Framework) for API documentation.

These default opinionated features were mostly derived from these projects:


Contributing

Discussions and pull requests are encouraged :) Please ask all general questions in this repo or pick a specialized repo for specific, targetted issues. We also have a contributing document which goes into detail about how to do this.

Code of Conduct

Yep, we also have a code of conduct which applies to all repositories in the (GitHub) Homely organisation.

Feedback

Yep, refer to the contributing page about how best to give feedback - either good or needs-improvement :)