/// <summary>
/// https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/752#issuecomment-467817189
/// When Swashbuckle.AspNetCore 5.0 is released, we can remove it.
/// </summary>
/// <param name="options"></param>
public static void CustomDefaultSchemaIdSelector(this SwaggerGenOptions options)
{
string SchemaIdSelector(Type modelType)
{
if (!modelType.IsConstructedGenericType)
{
return(modelType.Name);
}
var prefix = modelType.GetGenericArguments()
.Select(SchemaIdSelector)
.Aggregate <string>((previous, current) => previous + current);
return(modelType.Name.Split('`').First() + "Of" + prefix);
}
options.CustomSchemaIds(SchemaIdSelector);
}
/// <summary>
///
/// </summary>
/// <param name="swaggerGenOptions"></param>
protected virtual void ConfigureSwagger(SwaggerGenOptions swaggerGenOptions)
{
swaggerGenOptions.SwaggerDoc(Constants.ApiVersions.V1, new Info
{
Version = Constants.Swagger.ApiVersions.V1.Version,
Title = Constants.Swagger.ApiVersions.V1.Title,
Description = Constants.Swagger.ApiVersions.V1.Description,
TermsOfService = Constants.Swagger.ApiVersions.V1.TermsOfService,
Contact = new Contact()
{
Name = Constants.Swagger.Contact.Name, Email = Constants.Swagger.Contact.Email, Url = Constants.Swagger.Contact.Url
}
});
swaggerGenOptions.CustomSchemaIds(x => x.FullName);
swaggerGenOptions.IncludeXmlComments(GetXmlCommentsPath());
swaggerGenOptions.DescribeAllEnumsAsStrings();
swaggerGenOptions.OperationFilter <MultipleOperationsWithSameVerbFilter>();
}
/// <summary>
/// 基础配置
/// </summary>
/// <param name="options"></param>
/// <param name="title"></param>
private static void BasicConfig(SwaggerGenOptions options, string title)
{
if (string.IsNullOrEmpty(title))
{
title = "Dry API";
}
options.CustomSchemaIds(type => type.ToString());
options.SwaggerDoc("v1", new OpenApiInfo
{
Title = title,
Version = "v1",
});
options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, "*.xml").ToList().ForEach(file =>
{
options.IncludeXmlComments(file, true);
});
}
/// <summary>
/// Configure the swagger settings.
/// </summary>
/// <param name="swaggerGenOptions">The <see cref="SwaggerGenOptions"/> to use.</param>
/// <param name="assemblyDocumentationPath">The path to the XML documentation file for the <see cref="Host"/> assembly.</param>
/// <param name="apiDocumentationPath">The path to the XML documentation file for the <see cref="Api"/> assembly.</param>
public static void Configure(SwaggerGenOptions swaggerGenOptions, string assemblyDocumentationPath, string apiDocumentationPath)
{
swaggerGenOptions.SwaggerDoc(
"v1",
new OpenApiInfo
{
Title = "TGS API",
Version = ApiHeaders.Version.Semver().ToString(),
License = new OpenApiLicense
{
Name = "AGPL-3.0",
Url = new Uri("https://github.com/tgstation/tgstation-server/blob/dev/LICENSE")
},
Contact = new OpenApiContact
{
Name = "/tg/station 13",
Url = new Uri("https://github.com/tgstation")
},
Description = "A production scale tool for BYOND server management"
});
// Important to do this before applying our own filters
// Otherwise we'll get NullReferenceExceptions on parameters to be setup in our document filter
swaggerGenOptions.IncludeXmlComments(assemblyDocumentationPath);
swaggerGenOptions.IncludeXmlComments(apiDocumentationPath);
// nullable stuff
swaggerGenOptions.UseAllOfToExtendReferenceSchemas();
swaggerGenOptions.OperationFilter <SwaggerConfiguration>();
swaggerGenOptions.DocumentFilter <SwaggerConfiguration>();
swaggerGenOptions.SchemaFilter <SwaggerConfiguration>();
swaggerGenOptions.CustomSchemaIds(type =>
{
if (type == typeof(Api.Models.Internal.UserBase))
{
return("ShallowUser");
}
if (type == typeof(Api.Models.Internal.UserGroup))
{
return("ShallowUserGroup");
}
if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Paginated <>))
{
return($"Paginated{type.GenericTypeArguments.First().Name}");
}
return(type.Name);
});
swaggerGenOptions.AddSecurityDefinition(PasswordSecuritySchemeId, new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Type = SecuritySchemeType.Http,
Name = HeaderNames.Authorization,
Scheme = ApiHeaders.BasicAuthenticationScheme
});
swaggerGenOptions.AddSecurityDefinition(OAuthSecuritySchemeId, new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Type = SecuritySchemeType.Http,
Name = HeaderNames.Authorization,
Scheme = ApiHeaders.OAuthAuthenticationScheme
});
swaggerGenOptions.AddSecurityDefinition(TokenSecuritySchemeId, new OpenApiSecurityScheme
{
BearerFormat = "JWT",
In = ParameterLocation.Header,
Type = SecuritySchemeType.Http,
Name = HeaderNames.Authorization,
Scheme = ApiHeaders.BearerAuthenticationScheme
});
}
public static SwaggerGenOptions AddElectSwaggerGenOptions([NotNull] SwaggerGenOptions swaggerGenOptions, [NotNull] Action <ElectSwaggerOptions> configuration)
{
var options = configuration.GetValue();
// Doc Info
swaggerGenOptions.SwaggerDoc(options.Version, new Info
{
Title = options.Title,
Version = options.Version,
Contact = !string.IsNullOrWhiteSpace(options.AuthorName) &&
!string.IsNullOrWhiteSpace(options.AuthorWebsite) &&
!string.IsNullOrWhiteSpace(options.AuthorEmail)
? new Contact
{
Name = options.AuthorName,
Url = options.AuthorWebsite,
Email = options.AuthorEmail
}
: null
});
// XML
IncludeXmlCommentsIfExists(swaggerGenOptions, Assembly.GetEntryAssembly());
// Filers
swaggerGenOptions.OperationFilter <ApiDocGroupOperationFilter>();
swaggerGenOptions.OperationFilter <GlobalParameterOperationFilter>();
swaggerGenOptions.OperationFilter <ParameterOperationFilter>();
swaggerGenOptions.DocumentFilter <ShowHideInApiDocDocumentFilter>();
swaggerGenOptions.IgnoreObsoleteProperties();
swaggerGenOptions.IgnoreObsoleteActions();
// Type / Properties
if (options.IsFullSchemaForType)
{
swaggerGenOptions.CustomSchemaIds(type => type.FullName);
}
if (options.IsDescribeAllParametersInCamelCase)
{
swaggerGenOptions.DescribeAllParametersInCamelCase();
}
if (options.IsDescribeAllEnumsAsString)
{
swaggerGenOptions.DescribeAllEnumsAsStrings();
if (options.IsDescribeAllParametersInCamelCase)
{
swaggerGenOptions.DescribeStringEnumsInCamelCase();
}
}
// Order
swaggerGenOptions.OrderActionsBy(apiDesc => apiDesc.ActionDescriptor.DisplayName);
return(swaggerGenOptions);
}
internal static void IncludeFullNameCustomSchemaId(this SwaggerGenOptions options)
{
options.CustomSchemaIds(x => x.FullName);
}
public static void UseFullTypeNameInSchemaIds(this SwaggerGenOptions options) => options.CustomSchemaIds(x => x.FriendlyId(true));
public static SwaggerGenOptions AddElectSwaggerGenOptions([NotNull] SwaggerGenOptions swaggerGenOptions,
[NotNull] Action <ElectSwaggerOptions> configuration)
{
var options = configuration.GetValue();
// Doc Info
swaggerGenOptions.SwaggerDoc(options.Version, new OpenApiInfo
{
Title = options.Title,
Version = options.Version,
Contact = !string.IsNullOrWhiteSpace(options.AuthorName) &&
!string.IsNullOrWhiteSpace(options.AuthorWebsite) &&
!string.IsNullOrWhiteSpace(options.AuthorEmail)
? new OpenApiContact
{
Name = options.AuthorName,
Url = string.IsNullOrWhiteSpace(options.AuthorWebsite) ? null : new Uri(options.AuthorWebsite),
Email = options.AuthorEmail
}
: null
});
// XML
IncludeXmlCommentsIfExists(swaggerGenOptions, Assembly.GetEntryAssembly());
// Operation Filters
swaggerGenOptions.OperationFilter <ApiDescriptionPropertiesOperationFilter>();
swaggerGenOptions.OperationFilter <ApiDocGroupOperationFilter>();
swaggerGenOptions.OperationFilter <GlobalParameterOperationFilter>();
swaggerGenOptions.OperationFilter <ParameterOperationFilter>();
// Document Filters
swaggerGenOptions.DocumentFilter <ShowHideInApiDocDocumentFilter>();
swaggerGenOptions.IgnoreObsoleteProperties();
swaggerGenOptions.IgnoreObsoleteActions();
// Type / Properties
if (options.IsFullSchemaForType)
{
swaggerGenOptions.CustomSchemaIds(type => type.FullName);
}
// Order
swaggerGenOptions.OrderActionsBy((apiDesc) =>
{
var apiDisplayName = apiDesc.ActionDescriptor.DisplayName;
if (!apiDesc.Properties.TryGetValue(nameof(OpenApiOperation.Summary), out var summary))
{
return(apiDisplayName);
}
if (!string.IsNullOrWhiteSpace(summary?.ToString()))
{
apiDisplayName = summary.ToString();
}
return(apiDisplayName);
});
return(swaggerGenOptions);
}