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
ApiContact	No	The primary contact for the API	None
SwaggerEndpointUrl	No	The url to use for the swagger documentation.	/swagger/v1/swagger.json
SwaggerEndpointName	No	The name to use on the main swagger documentation page.	None
LicenseName	No	The name of the license on the swagger documentation.	None
LicenseUrl	No	The url of the license on the swagger documentation.	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!
  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