/// <summary>
/// Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML Comment files
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="filePath">An abolsute path to the file that contains XML Comments</param>
/// <param name="includeControllerXmlComments">
/// Flag to indicate if controller XML comments (i.e. summary) should be used to assign Tag descriptions.
/// Don't set this flag if you're customizing the default tag for operations via TagActionsBy.
/// </param>
public static void IncludeXmlComments(
this DocumentGenOptions swaggerGenOptions,
string filePath,
bool includeControllerXmlComments = false)
{
swaggerGenOptions.IncludeXmlComments(() => new XPathDocument(filePath), includeControllerXmlComments);
}
/// <summary>
/// Add one or more "securityDefinitions", describing how your API is protected, to the generated Swagger
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="name">A unique name for the scheme, as per the Swagger spec.</param>
/// <param name="securityScheme">
/// A description of the scheme - can be an instance of BasicAuthScheme, ApiKeyScheme or OAuth2Scheme
/// </param>
public static void AddSecurityDefinition(
this DocumentGenOptions swaggerGenOptions,
string name,
OpenApiSecurityScheme securityScheme)
{
swaggerGenOptions.SwaggerGeneratorOptions.SecuritySchemes.Add(name, securityScheme);
}
/// <summary>
/// Define one or more documents to be created by the Swagger generator
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="name">A URI-friendly name that uniquely identifies the document</param>
/// <param name="info">Global metadata to be included in the Swagger output</param>
public static void SwaggerDoc(
this DocumentGenOptions swaggerGenOptions,
string name,
OpenApiInfo info)
{
swaggerGenOptions.SwaggerGeneratorOptions.SwaggerDocs.Add(name, info);
}
/// <summary>
/// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="type">System type</param>
/// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>
public static void MapType(
this DocumentGenOptions swaggerGenOptions,
Type type,
Func <OpenApiSchema> schemaFactory)
{
swaggerGenOptions.SchemaGeneratorOptions.CustomTypeMappings.Add(type, schemaFactory);
}
/// <summary>
/// Generate polymorphic schemas (i.e. "oneOf") based on discovered subtypes
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="subTypesResolver"></param>
public static void GeneratePolymorphicSchemas(this DocumentGenOptions swaggerGenOptions, Func <Type, IEnumerable <Type> > subTypesResolver = null)
{
swaggerGenOptions.SchemaGeneratorOptions.GeneratePolymorphicSchemas = true;
if (subTypesResolver != null)
{
swaggerGenOptions.SchemaGeneratorOptions.SubTypesResolver = subTypesResolver;
}
}
/// <summary>
/// Extend the Swagger Generator with "filters" that can modify SwaggerDocuments after they're initially generated
/// </summary>
/// <typeparam name="TFilter">A type that derives from IDocumentFilter</typeparam>
/// <param name="swaggerGenOptions"></param>
/// <param name="arguments">Optionally inject parameters through filter constructors</param>
public static void DocumentFilter <TFilter>(
this DocumentGenOptions swaggerGenOptions,
params object[] arguments)
where TFilter : IDocumentFilter
{
swaggerGenOptions.DocumentFilterDescriptors.Add(new FilterDescriptor
{
Type = typeof(TFilter),
Arguments = arguments
});
}
/// <summary>
/// Inject human-friendly descriptions for Operations, Parameters and Schemas based on XML Comment files
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="xmlDocFactory">A factory method that returns XML Comments as an XPathDocument</param>
/// <param name="includeControllerXmlComments">
/// Flag to indicate if controller XML comments (i.e. summary) should be used to assign Tag descriptions.
/// Don't set this flag if you're customizing the default tag for operations via TagActionsBy.
/// </param>
public static void IncludeXmlComments(
this DocumentGenOptions swaggerGenOptions,
Func <XPathDocument> xmlDocFactory,
bool includeControllerXmlComments = false)
{
var xmlDoc = xmlDocFactory();
swaggerGenOptions.OperationFilter <XmlCommentsOperationFilter>(xmlDoc);
swaggerGenOptions.SchemaFilter <XmlCommentsSchemaFilter>(xmlDoc);
if (includeControllerXmlComments)
{
swaggerGenOptions.DocumentFilter <XmlCommentsDocumentFilter>(xmlDoc);
}
}
/// <summary>
/// Provide a custom strategy for selecting actions.
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="predicate">
/// A lambda that returns true/false based on document name and ApiDescription
/// </param>
public static void DocInclusionPredicate(
this DocumentGenOptions swaggerGenOptions,
Func <string, ApiDescription, bool> predicate)
{
swaggerGenOptions.SwaggerGeneratorOptions.DocInclusionPredicate = predicate;
}
/// <summary>
/// Provide a custom strategy for assigning "tags" to actions
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="tagsSelector"></param>
public static void TagActionsBy(
this DocumentGenOptions swaggerGenOptions,
Func <ApiDescription, IList <string> > tagsSelector)
{
swaggerGenOptions.SwaggerGeneratorOptions.TagsSelector = tagsSelector;
}
/// <summary>
/// Provide a custom strategy for assigning "operationId" to operations
/// </summary>
public static void CustomOperationIds(
this DocumentGenOptions swaggerGenOptions,
Func <ApiDescription, string> operationIdSelector)
{
swaggerGenOptions.SwaggerGeneratorOptions.OperationIdSelector = operationIdSelector;
}
/// <summary>
/// Use referenced schema definitions instead of inline schema's for enum types
/// </summary>
public static void UseReferencedDefinitionsForEnums(this DocumentGenOptions swaggerGenOptions)
{
swaggerGenOptions.SchemaGeneratorOptions.UseReferencedDefinitionsForEnums = true;
}
/// <summary>
/// If applicable, describe all enum names, regardless of how they appear in code, in camelCase.
/// </summary>
public static void DescribeStringEnumsInCamelCase(this DocumentGenOptions swaggerGenOptions)
{
swaggerGenOptions.SchemaGeneratorOptions.DescribeStringEnumsInCamelCase = true;
}
/// <summary>
/// Use the enum names, as opposed to their integer values, when describing enum types
/// </summary>
public static void DescribeAllEnumsAsStrings(this DocumentGenOptions swaggerGenOptions)
{
swaggerGenOptions.SchemaGeneratorOptions.DescribeAllEnumsAsStrings = true;
}
/// <summary>
/// Provide a custom mapping, for a given type, to the Swagger-flavored JSONSchema
/// </summary>
/// <typeparam name="T">System type</typeparam>
/// <param name="swaggerGenOptions"></param>
/// <param name="schemaFactory">A factory method that generates Schema's for the provided type</param>
public static void MapType <T>(
this DocumentGenOptions swaggerGenOptions,
Func <OpenApiSchema> schemaFactory)
{
swaggerGenOptions.MapType(typeof(T), schemaFactory);
}
/// <summary>
/// Adds a global security requirement
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="securityRequirement">
/// A dictionary of required schemes (logical AND). Keys must correspond to schemes defined through AddSecurityDefinition
/// If the scheme is of type "oauth2", then the value is a list of scopes, otherwise it MUST be an empty array
/// </param>
public static void AddSecurityRequirement(
this DocumentGenOptions swaggerGenOptions,
OpenApiSecurityRequirement securityRequirement)
{
swaggerGenOptions.SwaggerGeneratorOptions.SecurityRequirements.Add(securityRequirement);
}
/// <summary>
/// Ignore any actions that are decorated with the ObsoleteAttribute
/// </summary>
public static void IgnoreObsoleteActions(this DocumentGenOptions swaggerGenOptions)
{
swaggerGenOptions.SwaggerGeneratorOptions.IgnoreObsoleteActions = true;
}
/// <summary>
/// Merge actions that have conflicting HTTP methods and paths (must be unique for Swagger 2.0)
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="resolver"></param>
public static void ResolveConflictingActions(
this DocumentGenOptions swaggerGenOptions,
Func <IEnumerable <ApiDescription>, ApiDescription> resolver)
{
swaggerGenOptions.SwaggerGeneratorOptions.ConflictingActionsResolver = resolver;
}
/// <summary>
/// Provide a custom strategy for generating the unique Id's that are used to reference object Schema's
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="schemaIdSelector">
/// A lambda that returns a unique identifier for the provided system type
/// </param>
public static void CustomSchemaIds(
this DocumentGenOptions swaggerGenOptions,
Func <Type, string> schemaIdSelector)
{
swaggerGenOptions.SchemaGeneratorOptions.SchemaIdSelector = schemaIdSelector;
}
public static void TagActionsBy(
this DocumentGenOptions swaggerGenOptions,
Func <ApiDescription, string> tagSelector)
{
swaggerGenOptions.SwaggerGeneratorOptions.TagsSelector = (apiDesc) => new[] { tagSelector(apiDesc) };
}
/// <summary>
/// Ignore any properties that are decorated with the ObsoleteAttribute
/// </summary>
public static void IgnoreObsoleteProperties(this DocumentGenOptions swaggerGenOptions)
{
swaggerGenOptions.SchemaGeneratorOptions.IgnoreObsoleteProperties = true;
}
/// <summary>
/// Provide a custom strategy for sorting actions before they're transformed into the Swagger format
/// </summary>
/// <param name="swaggerGenOptions"></param>
/// <param name="sortKeySelector"></param>
public static void OrderActionsBy(
this DocumentGenOptions swaggerGenOptions,
Func <ApiDescription, string> sortKeySelector)
{
swaggerGenOptions.SwaggerGeneratorOptions.SortKeySelector = sortKeySelector;
}
/// <summary>
/// Describe all parameters, regardless of how they appear in code, in camelCase
/// </summary>
public static void DescribeAllParametersInCamelCase(this DocumentGenOptions swaggerGenOptions)
{
swaggerGenOptions.SwaggerGeneratorOptions.DescribeAllParametersInCamelCase = true;
}
