Swagger/OpenAPI File Settings

Settings for adding detailed swagger documentation to your Web API.

Swagger

If desired, you can add a basic swagger configuration using the SwaggerConfig option. This will scaffold out a bare bones swagger page using Swashbuckle, which you can update to use any additional features you wish.

Of note, you can scaffold out detailed swagger comments for each of your endpoints using the AddSwaggerComments property.

To get to your swagger page, you can go to /swagger.

Swagger Properties

NameRequiredDescriptionDefault
TitleYesThe title of the swagger documentNone
DescriptionNoThe description for your swagger docNone
ApiContactNoThe primary contact for the APINone
SwaggerEndpointUrlNoThe url to use for the swagger documentation./swagger/v1/swagger.json
SwaggerEndpointNameNoThe name to use on the main swagger documentation page.None
LicenseNameNoThe name of the license on the swagger documentation.None
LicenseUrlNoThe url of the license on the swagger documentation.None
AddSwaggerCommentsNoDetermines whether or not Craftsman should scaffold out detailed swagger comments for each endpoint.false

ApiContact Properties

NameRequiredDescriptionDefault
NameNoThe name of the contactNone
EmailNoThe email of the contactNone
UrlNoThe website for the contactNone

AddSwaggerComments Property

If set to true, Craftsman will scaffold out detailed comments on using each endpoint. The largest impact is on the details of using the GET list/collection endpoint and will discuss how to use pagination, filters, and sorting.

Swagger Comments on Parameters

If you'd like to add comments to the parameters directly, you'll need to follow the steps below on the Application project.

  1. Double click the Application.csproj project to open the properties.

  2. Under the PropertyGroup section, add a documentation file line and make sure you have a 1591 item added to `NoWarn:

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>YourProjectNameHere.Application.xml</DocumentationFile>
    <NoWarn>1701;1702;1591</NoWarn>
  </PropertyGroup>
  1. Go to the WebApi.ServiceExtensions and add an additional IncludeXmlComments line that includes the new path like so:
  config.IncludeXmlComments(string.Format(@"{0}\YourProjectNameHere.Application.xml", AppDomain.CurrentDomain.BaseDirectory));
  1. Add any comments above specific properties however you wish

Swagger Example

SwaggerConfig:
  Title: Carbon Kitchen API
  Description: Manage everything in your kitchen!
  SwaggerEndpointName: Carbon Kitchen API
  LicenseName: MIT
  LicenseUrl: https://carbonkitchen.com/license
  AddSwaggerComments: true
  ApiContact:
    Name: Carbon Kitchen Support
    Email: support@carbonkitchen.com
    Url: https://www.carbonkitchen.com/support