Swagger/OpenAPI File Settings

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

Name	Required	Description	Default
Title	Yes	The title of the swagger document	None
Description	No	The description for your swagger doc	None
AddSwaggerComments	No	Determines whether or not Craftsman should scaffold out detailed swagger comments for each endpoint.	false

ApiContact Properties

Name	Required	Description	Default
Name	No	The name of the contact	None
Email	No	The email of the contact	None
Url	No	The website for the contact	None

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.

Double click the Application.csproj project to open the properties.
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>

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));

Add any comments above specific properties however you wish

Swagger Example

SwaggerConfig:
  Title: Carbon Kitchen API
  Description: Manage everything in your kitchen!
  AddSwaggerComments: true