private static void InitializeOpenApiDocumentOptions(AspNetCoreOpenApiDocumentGeneratorSettings options, string version)
{
options.DocumentName = version;
options.Title = $"Elastic demo API {version}";
options.ApiGroupNames = new[] { version };
options.Description = "Elastic demo API";
options.IgnoreObsoleteProperties = true;
}
/// <summary>Configure SwaggerDocument.</summary>
/// <param name="settings"><see cref="AspNetCoreOpenApiDocumentGeneratorSettings"/></param>
/// <param name="services"><see cref="IServiceProvider"/></param>
protected virtual void ConfigureOpenApiDocument(AspNetCoreOpenApiDocumentGeneratorSettings settings, IServiceProvider services)
{
var informationalVersion = _assembly.GetCustomAttribute <AssemblyInformationalVersionAttribute>()
.InformationalVersion;
settings.Version = informationalVersion;
settings.Description = ApiInfo.Description;
settings.Title = ApiInfo.DisplayName;
settings.PostProcess = PostProcess;
settings.SchemaType = SchemaType.OpenApi3;
}
public override void Apply(AspNetCoreOpenApiDocumentGeneratorSettings document)
{
var _in = EnumEx.Parse <OpenApiSecurityApiKeyLocation>(this?.Location.ToString());
document.AddSecurity(this?.SecurityName ?? SwaggerNSwagExtensions.DefaultSecurityName /*, new[] { "skoruba_identity_admin_api" }*/, new NSwag.OpenApiSecurityScheme
{
Description = this?.Description,
Name = this?.Name,
Type = NSwag.OpenApiSecuritySchemeType.Basic
});
}
/// <summary>
///
/// </summary>
/// <param name="configure"></param>
internal static void AddJWTSecurity(this AspNetCoreOpenApiDocumentGeneratorSettings configure)
{
configure.AddSecurity("JWT", Enumerable.Empty <string>(), new OpenApiSecurityScheme
{
Type = OpenApiSecuritySchemeType.ApiKey,
Name = "Authorization",
In = OpenApiSecurityApiKeyLocation.Header,
Description = "Type into the textbox: Bearer {your JWT token}."
});
configure.OperationProcessors.Add(new AspNetCoreOperationSecurityScopeProcessor("JWT"));
}
public async Task When_complex_body_parameter_has_default_value_then_it_is_optional()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(BodyParametersController));
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "BodyParameters_RequiredComplexWithDefault").Operation;
Assert.True(operation.ActualParameters.First().IsRequired);
}
/// <summary>
/// Установить параметры swagger
/// </summary>
public static void ConfigSwagger(AspNetCoreOpenApiDocumentGeneratorSettings config) =>
config.PostProcess = document =>
{
document.Info.Version = "v1";
document.Info.Title = "Boutique API";
document.Info.Description = "Clothes Web Api for VeraBoutique store";
document.Info.Contact = new NSwag.OpenApiContact
{
Name = "Ivan Rubilnik",
Email = "*****@*****.**",
Url = "https://github.com/rubilnik4/VeraBoutique"
};
};
public async Task When_primitive_body_parameter_has_no_default_value_then_it_is_required()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(ActualController));
var json = document.ToJson();
// Assert
Assert.True(document.Operations.Any());
}
protected async Task <OpenApiDocument> GenerateDocumentAsync(AspNetCoreOpenApiDocumentGeneratorSettings settings, params Type[] controllerTypes)
{
var generator = new AspNetCoreOpenApiDocumentGenerator(settings);
var provider = TestServer.Host.Services.GetRequiredService <IApiDescriptionGroupCollectionProvider>();
var controllerTypeNames = controllerTypes.Select(t => t.FullName);
var groups = new ApiDescriptionGroupCollection(provider.ApiDescriptionGroups.Items
.Select(i => new ApiDescriptionGroup(i.GroupName, i.Items.Where(u => controllerTypeNames.Contains(((ControllerActionDescriptor)u.ActionDescriptor).ControllerTypeInfo.FullName)).ToList())).ToList(),
provider.ApiDescriptionGroups.Version);
var document = await generator.GenerateAsync(groups);
return(document);
}
public async Task When_operation_has_SwaggerResponseAttribute_with_description_it_is_in_the_spec()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(XmlDocsController));
var json = document.ToJson();
// Assert
Assert.Contains("My response.", json);
Assert.Contains("My property.", json);
}
public async Task When_controller_has_extension_data_attributes_then_they_are_processed()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(SwaggerExtensionDataController));
// Assert
Assert.Equal(2, document.ExtensionData.Count);
Assert.Equal("b", document.ExtensionData["a"]);
Assert.Equal("y", document.ExtensionData["x"]);
}
public async Task When_route_is_empty_then_path_is_slash()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(EmptyPathController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "EmptyPath_Get");
Assert.Equal("/", operation.Path);
}
public async Task When_operation_has_SwaggerResponseAttribute_with_description_it_is_in_the_spec()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(ResponsesController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First().Operation;
Assert.Equal("Foo.", operation.ActualResponses.First().Value.Description);
}
public async Task When_route_is_not_empty_then_path_starts_with_slash()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(BodyParametersController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "BodyParameters_RequiredPrimitive");
Assert.StartsWith("/", operation.Path);
}
public async Task When_model_binder_parameter_is_used_on_path_parameter_then_parameter_kind_is_path()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
RequireParametersWithoutDefault = true
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(PathParameterWithModelBinderController));
// Assert
var kind = document.Operations.First().Operation.Parameters.First().Kind;
Assert.Equal(OpenApiParameterKind.Path, kind);
}
public async Task When_parameter_is_overwritten_then_original_name_is_set()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
RequireParametersWithoutDefault = false
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(RenamedQueryParameterController));
// Assert
var parameter = document.Operations.First().Operation.ActualParameters.First();
Assert.Equal("month", parameter.Name);
Assert.Equal("months", parameter.OriginalName);
}
public async Task When_consumes_is_defined_on_all_operations_then_it_is_added_to_the_document()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(ConsumesController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "Consumes_ConsumesOnOperation").Operation;
Assert.Contains("text/html", document.Consumes);
Assert.Contains("text/html", operation.ActualConsumes);
}
public async Task WhenOperationHasFormDataFile_ThenItIsInRequestBody()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
SchemaType = SchemaType.OpenApi3
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(FileUploadController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "FileUpload_UploadFile").Operation;
var schema = operation.RequestBody.Content["multipart/form-data"].Schema;
Assert.Equal("binary", schema.Properties["file"].Format);
Assert.Equal(JsonObjectType.String, schema.Properties["file"].Type);
Assert.Equal(JsonObjectType.String, schema.Properties["test"].Type);
Assert.Contains(@" ""/api/FileUpload/UploadFiles"": {
""post"": {
""tags"": [
""FileUpload""
],
""operationId"": ""FileUpload_UploadFiles"",
""requestBody"": {
""content"": {
""multipart/form-data"": {
""schema"": {
""properties"": {
""files"": {
""type"": ""array"",
""items"": {
""type"": ""string"",
""format"": ""binary""
}
},
""test"": {
""type"": ""string""
}
}
}
}
}
},", json);
}
public async Task When_handling_is_Null_then_response_is_nullable()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings
{
SchemaType = SchemaType.OpenApi3,
DefaultResponseReferenceTypeNullHandling = ReferenceTypeNullHandling.Null
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(ResponsesController));
// Assert
var operation = document.Operations.First().Operation;
Assert.True(operation.ActualResponses.First().Value.Schema.IsNullable(SchemaType.OpenApi3));
}
public async Task When_complex_query_parameters_are_nullable_and_set_to_null_they_are_optional_in_spec()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
RequireParametersWithoutDefault = true
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(HeaderParametersController));
// Assert
var operation = document.Operations.First().Operation;
Assert.Equal(2, operation.ActualParameters.Count);
Assert.True(operation.ActualParameters.First().IsRequired);
Assert.False(operation.ActualParameters.Last().IsRequired);
}
public async Task When_api_version_parameter_should_be_ignored_then_it_is_ignored()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
settings.ApiGroupNames = new[] { "1" };
// Act
var document = await GenerateDocumentAsync(settings, typeof(VersionedValuesController), typeof(VersionedV3ValuesController));
var json = document.ToJson();
// Assert
var operations = document.Operations;
Assert.True(operations.All(o => o.Operation.ActualParameters.All(p => p.Name != "api-version")));
}
public async Task When_nullable_xml_docs_is_not_set_then_default_setting_NotNull_is_used()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings
{
SchemaType = SchemaType.OpenApi3,
DefaultResponseReferenceTypeNullHandling = ReferenceTypeNullHandling.NotNull
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(NullableResponseController));
// Assert
var operation = document.Operations.First(o => o.Path.Contains(nameof(NullableResponseController.OperationWithNoXmlDocs))).Operation;
Assert.False(operation.ActualResponses.First().Value.Schema.IsNullable(SchemaType.OpenApi3));
}
public async Task When_operation_has_extension_data_attributes_then_they_are_processed()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
// Act
var document = await GenerateDocumentAsync(settings, typeof(SwaggerExtensionDataController));
// Assert
var extensionData = document.Operations.First().Operation.ExtensionData;
Assert.Equal(2, extensionData.Count);
Assert.Equal("b", document.Operations.First().Operation.ExtensionData["a"]);
Assert.Equal("y", document.Operations.First().Operation.ExtensionData["x"]);
Assert.Equal("foo", document.Operations.First().Operation.Parameters.First().Name);
Assert.Equal("d", document.Operations.First().Operation.Parameters.First().ExtensionData["c"]);
}
public async Task When_simple_query_parameter_has_BindRequiredAttribute_then_it_is_required()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
RequireParametersWithoutDefault = false
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(SimpleQueryParametersController));
// Assert
var operation = document.Operations.First().Operation;
Assert.Equal(3, operation.ActualParameters.Count);
Assert.False(operation.ActualParameters.Skip(0).First().IsRequired);
Assert.False(operation.ActualParameters.Skip(1).First().IsRequired);
Assert.True(operation.ActualParameters.Skip(2).First().IsRequired);
}
private void ConfigureOpenApiDocument(IConfiguration configuration, AspNetCoreOpenApiDocumentGeneratorSettings settings)
{
settings.DocumentName = "v1";
settings.Version = "v1";
settings.Title = this.GetType().Namespace;
settings.AddSecurity(
"bearer",
Enumerable.Empty <string>(),
new OpenApiSecurityScheme
{
Type = OpenApiSecuritySchemeType.OAuth2,
Flow = OpenApiOAuth2Flow.Implicit,
Description = "Oidc Authentication",
Flows = new OpenApiOAuthFlows
{
Implicit = new OpenApiOAuthFlow
{
AuthorizationUrl = $"{configuration["Oidc:Authority"]}/protocol/openid-connect/auth",
TokenUrl = $"{configuration["Oidc:Authority"]}/protocol/openid-connect/token",
Scopes = new Dictionary <string, string>
{
//{"openid", "openid"},
}
}
},
});
settings.OperationProcessors.Add(new ApiVersionProcessor());
settings.OperationProcessors.Add(new AspNetCoreOperationSecurityScopeProcessor("bearer"));
settings.OperationProcessors.Add(new AuthorizationOperationProcessor("bearer"));
settings.PostProcess = document =>
{
document.Info.Version = "v1";
document.Info.Title = this.GetType().Namespace;
document.Info.Description = "Weather API";
document.Info.TermsOfService = "http://www.weather.com";
document.Info.Contact = new OpenApiContact
{
Name = "John Doe",
Email = "*****@*****.**",
Url = "http://www.weather.com"
};
};
}
public async Task When_generating_versioned_controllers_then_version_path_parameter_is_not_present()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
};
settings.ApiGroupNames = new[] { "3" };
// Act
var document = await GenerateDocumentAsync(settings, typeof(VersionedValuesController), typeof(VersionedV3ValuesController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First();
// check that implict unused path parameter is not in the spec
Assert.DoesNotContain(operation.Operation.ActualParameters, p => p.Name == "version");
}
public async Task When_parameter_has_default_and_schema_type_is_OpenApi3_then_schema_default_is_set()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings
{
SchemaType = SchemaType.OpenApi3,
RequireParametersWithoutDefault = true
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(DefaultParametersController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Path.Contains(nameof(DefaultParametersController.WithDefault))).Operation;
Assert.Equal(5, operation.Parameters.First().Schema.Default);
}
public async Task When_generating_v3_then_only_v3_operations_are_included()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings();
settings.ApiGroupNames = new[] { "3" };
// Act
var document = await GenerateDocumentAsync(settings, typeof(VersionedValuesController), typeof(VersionedV3ValuesController));
// Assert
var operations = document.Operations;
Assert.Equal(5, operations.Count());
Assert.True(operations.All(o => o.Path.Contains("/v3/")));
// VersionedIgnoredValues tag should not be in json document
Assert.Equal(1, document.Tags.Count);
}
private static void InitAspNetCoreOpenApiDocumentGeneratorSettings(AspNetCoreOpenApiDocumentGeneratorSettings config, string documentName, IList <string> apiGroupNames, string documentVersion)
{
config.DocumentName = documentName;
config.ApiGroupNames = apiGroupNames.ToArray();
config.PostProcess = document =>
{
InitDocumentInfo(document, documentVersion);
};
config.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT"));
config.DocumentProcessors.Add(
new SecurityDefinitionAppender("JWT", new OpenApiSecurityScheme
{
Type = OpenApiSecuritySchemeType.ApiKey,
Name = "Authorization",
Description = "Bearer [Token]",
In = OpenApiSecurityApiKeyLocation.Header
})
);
}
public async Task When_OpenApiBodyParameter_is_applied_with_JSON_then_request_body_is_any_type()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
SchemaType = SchemaType.OpenApi3
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(PostBodyController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "PostBody_JsonPostBodyOperation").Operation;
var parameter = operation.Parameters.Single(p => p.Kind == OpenApiParameterKind.Body);
Assert.Equal(1, operation.Parameters.Count);
Assert.True(operation.RequestBody.Content["application/json"].Schema.IsAnyType);
}
public async Task When_OpenApiBodyParameter_is_applied_with_text_then_request_body_is_file()
{
// Arrange
var settings = new AspNetCoreOpenApiDocumentGeneratorSettings {
SchemaType = SchemaType.OpenApi3
};
// Act
var document = await GenerateDocumentAsync(settings, typeof(PostBodyController));
var json = document.ToJson();
// Assert
var operation = document.Operations.First(o => o.Operation.OperationId == "PostBody_FilePostBodyOperation").Operation;
var parameter = operation.Parameters.Single(p => p.Kind == OpenApiParameterKind.Body);
Assert.Equal(1, operation.Parameters.Count);
Assert.Equal(JsonObjectType.String, operation.RequestBody.Content["text/plain"].Schema.Type);
Assert.Equal("binary", operation.RequestBody.Content["text/plain"].Schema.Format);
}
