public void GenerateSchemaCustomSettingsShouldSucceed(
Type type,
OpenApiDocumentGenerationSettings generationSettings,
OpenApiSchema expectedSchema,
IDictionary <string, OpenApiSchema> expectedReferences)
{
_output.WriteLine(type.ToString());
// Arrange
var referenceRegistryManager =
new ReferenceRegistryManager(generationSettings);
// Act
var returnedSchema =
referenceRegistryManager.FindOrAddSchemaReference(type);
// Assert
var actualSchema = returnedSchema;
var actualReferences = referenceRegistryManager.SchemaReferenceRegistry.References;
_output.WriteLine(actualSchema.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0));
foreach (var reference in actualReferences)
{
_output.WriteLine(reference.Key);
_output.WriteLine(reference.Value.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0));
}
actualSchema.Should().BeEquivalentTo(expectedSchema);
actualReferences.Should().BeEquivalentTo(expectedReferences);
}
public void GenerateSchemaFromTypeShouldFail(
Type type,
string expectedExceptionMessage)
{
var referenceRegistryManager = new ReferenceRegistryManager();
Action action = () => referenceRegistryManager.FindOrAddSchemaReference(type);
action.Should().Throw <DocumentationException>(expectedExceptionMessage);
}
public void GenerateSchemaFromTypeShouldFail(
Type type,
string expectedExceptionMessage)
{
var referenceRegistryManager =
new ReferenceRegistryManager(
new OpenApiDocumentGenerationSettings(
new SchemaGenerationSettings(new DefaultPropertyNameResolver())));
Action action = () => referenceRegistryManager.FindOrAddSchemaReference(type);
action.Should().Throw <DocumentationException>(expectedExceptionMessage);
}
/// <summary>
/// Add operation and update the operation filter settings based on the given document variant info.
/// </summary>
private void AddOperation(
IDictionary <DocumentVariantInfo, OpenApiDocument> specificationDocuments,
IDictionary <DocumentVariantInfo, ReferenceRegistryManager> referenceRegistryManagerMap,
IList <GenerationError> operationGenerationErrors,
DocumentVariantInfo documentVariantInfo,
XElement operationElement,
XElement operationConfigElement,
TypeFetcher typeFetcher)
{
var paths = new OpenApiPaths();
foreach (var preprocessingOperationFilter in _preProcessingOperationFilters)
{
try
{
preprocessingOperationFilter.Apply(
paths,
operationElement,
new PreProcessingOperationFilterSettings());
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
);
}
}
if (!referenceRegistryManagerMap.ContainsKey(documentVariantInfo))
{
referenceRegistryManagerMap[documentVariantInfo] =
new ReferenceRegistryManager(_openApiDocumentGenerationSettings);
}
foreach (var pathToPathItem in paths)
{
var path = pathToPathItem.Key;
var pathItem = pathToPathItem.Value;
foreach (var operationMethodToOperation in pathItem.Operations)
{
var operationMethod = operationMethodToOperation.Key;
var operation = operationMethodToOperation.Value;
var operationFilterSettings = new OperationFilterSettings
{
TypeFetcher = typeFetcher,
ReferenceRegistryManager = referenceRegistryManagerMap[documentVariantInfo],
Path = path,
OperationMethod = operationMethod.ToString()
};
// Apply all the operation-related filters to extract information related to the operation.
// It is important that these are applied before the config filters below
// since the config filters may rely on information generated from operation filters.
foreach (var operationFilter in _operationFilters)
{
try
{
operationFilter.Apply(
operation,
operationElement,
operationFilterSettings);
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
);
}
}
if (operationConfigElement != null)
{
// Apply the config-related filters to extract information from the config xml
// that can be applied to the operations.
foreach (var configFilter in _operationConfigFilters)
{
try
{
configFilter.Apply(
operation,
operationConfigElement,
new OperationConfigFilterSettings
{
OperationFilterSettings = operationFilterSettings,
OperationFilters = _operationFilters
});
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
);
}
}
}
// Add the processed operation to the specification document.
if (!specificationDocuments.ContainsKey(documentVariantInfo))
{
specificationDocuments.Add(
documentVariantInfo,
new OpenApiDocument
{
Components = new OpenApiComponents(),
Paths = new OpenApiPaths()
});
}
// Copy operations from local Paths object to the Paths in the specification document.
var documentPaths = specificationDocuments[documentVariantInfo].Paths;
if (!documentPaths.ContainsKey(path))
{
documentPaths.Add(
path,
new OpenApiPathItem
{
Operations =
{
[operationMethod] = operation
}
});
}
else
{
if (documentPaths[path].Operations.ContainsKey(operationMethod))
{
throw new DuplicateOperationException(
path,
operationMethod.ToString(),
documentVariantInfo.Title);
}
documentPaths[path].Operations.Add(operationMethod, operation);
}
}
}
}
/// <summary>
/// Takes in annotation xml document and returns the OpenAPI document generation result
/// which contains OpenAPI specification document(s).
/// </summary>
/// <param name="annotationXmlDocuments">The list of XDocuments representing annotation xmls.</param>
/// <param name="contractAssemblyPaths">The contract assembly paths.</param>
/// <param name="configurationXml">The serialized XDocument representing the generation configuration.</param>
/// <param name="openApiDocumentVersion">The version of the OpenAPI document.</param>
/// <param name="openApiInfoDescription">The description to use while populating OpenApiInfo.</param>
/// <param name="generationDiagnostic">A string representing serialized version of
/// <see cref="GenerationDiagnostic"/>>
/// </param>
/// <returns>
/// Dictionary mapping document variant metadata to their respective OpenAPI document.
/// </returns>
public IDictionary <DocumentVariantInfo, OpenApiDocument> GenerateOpenApiDocuments(
IList <XDocument> annotationXmlDocuments,
IList <string> contractAssemblyPaths,
string configurationXml,
string openApiDocumentVersion,
string openApiInfoDescription,
out GenerationDiagnostic generationDiagnostic)
{
IDictionary <DocumentVariantInfo, OpenApiDocument> openApiDocuments
= new Dictionary <DocumentVariantInfo, OpenApiDocument>();
var operationElements = new List <XElement>();
var propertyElements = new List <XElement>();
foreach (var annotationXmlDocument in annotationXmlDocuments)
{
operationElements.AddRange(
annotationXmlDocument.XPathSelectElements("//doc/members/member[url and verb]"));
propertyElements.AddRange(annotationXmlDocument.XPathSelectElements("//doc/members/member")
.Where(
m => m.Attribute(KnownXmlStrings.Name) != null &&
m.Attribute(KnownXmlStrings.Name).Value.StartsWith("P:")));
}
XElement operationConfigElement = null;
XElement documentConfigElement = null;
var documentVariantElementNames = new List <string>();
if (!string.IsNullOrWhiteSpace(configurationXml))
{
var configurationXmlDocument = XDocument.Parse(configurationXml);
operationConfigElement = configurationXmlDocument.XPathSelectElement("//configuration/operation");
documentConfigElement = configurationXmlDocument.XPathSelectElement("//configuration/document");
documentVariantElementNames = configurationXmlDocument
.XPathSelectElements("//configuration/document/variant/name")
.Select(variantName => variantName.Value)
.ToList();
}
if (!operationElements.Any())
{
generationDiagnostic = new GenerationDiagnostic
{
DocumentGenerationDiagnostic = new DocumentGenerationDiagnostic
{
Errors =
{
new GenerationError
{
Message = SpecificationGenerationMessages.NoOperationElementFoundToParse
}
}
}
};
return(openApiDocuments);
}
try
{
var propertyNameResolverTypeName = _openApiDocumentGenerationSettings.SchemaGenerationSettings
.PropertyNameResolver.GetType().FullName;
var internalGenerationContext = new InternalGenerationContext();
var internalSchemaGenerationSettings = new InternalSchemaGenerationSettings()
{
PropertyNameResolverName = propertyNameResolverTypeName
};
generationDiagnostic = new GenerationDiagnostic();
var documentGenerationDiagnostic = new DocumentGenerationDiagnostic();
if (documentVariantElementNames?.Count > 1)
{
documentGenerationDiagnostic.Errors.Add(new GenerationError
{
Message = string.Format(
SpecificationGenerationMessages.MoreThanOneVariantNameNotAllowed,
documentVariantElementNames.First())
});
}
IList <string> serializedOperationElements = operationElements.Select(i => i.ToString()).ToList();
// Operation config elements can contain the types that needs to be fetched too,
// so add it to the list of operation elements which will be used to fetch type information.
if (operationConfigElement != null)
{
serializedOperationElements.Add(operationConfigElement.ToString());
}
#if !NETFRAMEWORK
var assemblyLoader = new AssemblyLoader.AssemblyLoader();
assemblyLoader.RegisterAssemblyPaths(contractAssemblyPaths);
var internalGenerationContextAsString = new AssemblyLoader.AssemblyLoader().BuildInternalGenerationContext(
contractAssemblyPaths,
serializedOperationElements,
propertyElements.Select(i => i.ToString()).ToList(),
documentVariantElementNames.FirstOrDefault(),
internalSchemaGenerationSettings);
internalGenerationContext =
(InternalGenerationContext)JsonConvert.DeserializeObject(
internalGenerationContextAsString,
typeof(InternalGenerationContext));
#else
using (var isolatedDomain = new AppDomainCreator <AssemblyLoader.AssemblyLoader>())
{
isolatedDomain.Object.RegisterAssemblyPaths(contractAssemblyPaths);
var internalGenerationContextAsString = isolatedDomain.Object.BuildInternalGenerationContext(
contractAssemblyPaths,
serializedOperationElements,
propertyElements.Select(i => i.ToString()).ToList(),
documentVariantElementNames.FirstOrDefault(),
internalSchemaGenerationSettings);
internalGenerationContext =
(InternalGenerationContext)JsonConvert.DeserializeObject(
internalGenerationContextAsString,
typeof(InternalGenerationContext));
}
#endif
GenerationContext generationContext = internalGenerationContext.ToGenerationContext();
var operationGenerationDiagnostics = GenerateSpecificationDocuments(
generationContext,
operationElements,
operationConfigElement,
documentVariantElementNames.FirstOrDefault(),
out var documents);
foreach (var operationGenerationDiagnostic in operationGenerationDiagnostics)
{
generationDiagnostic.OperationGenerationDiagnostics.Add(
new OperationGenerationDiagnostic(operationGenerationDiagnostic));
}
var referenceRegistryManager = new ReferenceRegistryManager(_openApiDocumentGenerationSettings);
foreach (var variantInfoDocumentValuePair in documents)
{
var openApiDocument = variantInfoDocumentValuePair.Value;
foreach (var documentFilter in _documentFilters)
{
var generationErrors = documentFilter.Apply(
openApiDocument,
annotationXmlDocuments,
new DocumentFilterSettings
{
OpenApiDocumentVersion = openApiDocumentVersion,
OpenApiInfoDescription = openApiInfoDescription,
ReferenceRegistryManager = referenceRegistryManager
},
_openApiDocumentGenerationSettings);
foreach (var error in generationErrors)
{
documentGenerationDiagnostic.Errors.Add(error);
}
}
foreach (var filter in _postProcessingDocumentFilters)
{
var generationErrors = filter.Apply(
openApiDocument,
new PostProcessingDocumentFilterSettings
{
OperationGenerationDiagnostics = operationGenerationDiagnostics
});
foreach (var error in generationErrors)
{
documentGenerationDiagnostic.Errors.Add(error);
}
}
referenceRegistryManager.SecuritySchemeReferenceRegistry.References.CopyInto(
openApiDocument.Components.SecuritySchemes);
}
if (documentConfigElement != null)
{
foreach (var documentConfigFilter in _documentConfigFilters)
{
var generationErrors = documentConfigFilter.Apply(
documents,
documentConfigElement,
annotationXmlDocuments,
new DocumentConfigFilterSettings());
foreach (var error in generationErrors)
{
documentGenerationDiagnostic.Errors.Add(error);
}
}
}
var failedOperations = generationDiagnostic.OperationGenerationDiagnostics
.Where(i => i.Errors.Count > 0);
if (failedOperations.Any())
{
var totalOperationsCount = generationDiagnostic.OperationGenerationDiagnostics.Count();
var exception = new UnableToGenerateAllOperationsException(
totalOperationsCount - failedOperations.Count(), totalOperationsCount);
documentGenerationDiagnostic.Errors.Add(
new GenerationError
{
ExceptionType = exception.GetType().Name,
Message = exception.Message
});
}
generationDiagnostic.DocumentGenerationDiagnostic = documentGenerationDiagnostic;
return(documents);
}
catch (Exception e)
{
generationDiagnostic = new GenerationDiagnostic
{
DocumentGenerationDiagnostic =
new DocumentGenerationDiagnostic
{
Errors =
{
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = string.Format(SpecificationGenerationMessages.UnexpectedError, e)
}
}
}
};
return(openApiDocuments);
}
}
/// <summary>
/// Takes in annotation xml document and returns the OpenAPI document generation result
/// which contains OpenAPI specification document(s).
/// </summary>
/// <param name="annotationXmlDocuments">The list of XDocuments representing annotation xmls.</param>
/// <param name="contractAssemblyPaths">The contract assembly paths.</param>
/// <param name="configurationXml">The serialized XDocument representing the generation configuration.</param>
/// <param name="openApiDocumentVersion">The version of the OpenAPI document.</param>
/// <param name="openApiInfoDescription">The description to use while populating OpenApiInfo.</param>
/// <param name="generationDiagnostic">A string representing serialized version of
/// <see cref="GenerationDiagnostic"/>>
/// </param>
/// <returns>
/// Dictionary mapping document variant metadata to their respective OpenAPI document.
/// </returns>
public IDictionary <DocumentVariantInfo, OpenApiDocument> GenerateOpenApiDocuments(
IList <XDocument> annotationXmlDocuments,
IList <string> contractAssemblyPaths,
string configurationXml,
string openApiDocumentVersion,
string openApiInfoDescription,
out GenerationDiagnostic generationDiagnostic)
{
IDictionary <DocumentVariantInfo, OpenApiDocument> openApiDocuments
= new Dictionary <DocumentVariantInfo, OpenApiDocument>();
var operationElements = new List <XElement>();
foreach (var annotationXmlDocument in annotationXmlDocuments)
{
operationElements.AddRange(
annotationXmlDocument.XPathSelectElements("//doc/members/member[url and verb]"));
}
XElement operationConfigElement = null;
XElement documentConfigElement = null;
var documentVariantElementNames = new List <string>();
if (!string.IsNullOrWhiteSpace(configurationXml))
{
var configurationXmlDocument = XDocument.Parse(configurationXml);
operationConfigElement = configurationXmlDocument.XPathSelectElement("//configuration/operation");
documentConfigElement = configurationXmlDocument.XPathSelectElement("//configuration/document");
documentVariantElementNames = configurationXmlDocument
.XPathSelectElements("//configuration/document/variant/name")
.Select(variantName => variantName.Value)
.ToList();
}
if (!operationElements.Any())
{
generationDiagnostic = new GenerationDiagnostic
{
DocumentGenerationDiagnostic = new DocumentGenerationDiagnostic
{
Errors =
{
new GenerationError
{
Message = SpecificationGenerationMessages.NoOperationElementFoundToParse
}
}
}
};
return(openApiDocuments);
}
try
{
generationDiagnostic = new GenerationDiagnostic();
var documentGenerationDiagnostic = new DocumentGenerationDiagnostic();
if (documentVariantElementNames?.Count > 1)
{
documentGenerationDiagnostic.Errors.Add(new GenerationError
{
Message = string.Format(
SpecificationGenerationMessages.MoreThanOneVariantNameNotAllowed,
documentVariantElementNames.First())
});
}
var typeFetcher = new TypeFetcher(contractAssemblyPaths);
var operationGenerationDiagnostics = GenerateSpecificationDocuments(
typeFetcher,
operationElements,
operationConfigElement,
documentVariantElementNames.FirstOrDefault(),
out var documents);
foreach (var operationGenerationDiagnostic in operationGenerationDiagnostics)
{
generationDiagnostic.OperationGenerationDiagnostics.Add(
new OperationGenerationDiagnostic(operationGenerationDiagnostic));
}
var referenceRegistryManager = new ReferenceRegistryManager(_openApiDocumentGenerationSettings);
foreach (var variantInfoDocumentValuePair in documents)
{
var openApiDocument = variantInfoDocumentValuePair.Value;
foreach (var documentFilter in _documentFilters)
{
try
{
documentFilter.Apply(
openApiDocument,
annotationXmlDocuments,
new DocumentFilterSettings
{
TypeFetcher = typeFetcher,
OpenApiDocumentVersion = openApiDocumentVersion,
OpenApiInfoDescription = openApiInfoDescription,
ReferenceRegistryManager = referenceRegistryManager
},
_openApiDocumentGenerationSettings);
}
catch (Exception e)
{
documentGenerationDiagnostic.Errors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
});
}
}
foreach (var filter in _postProcessingDocumentFilters)
{
filter.Apply(
openApiDocument,
new PostProcessingDocumentFilterSettings
{
OperationGenerationDiagnostics = operationGenerationDiagnostics
});
}
referenceRegistryManager.SecuritySchemeReferenceRegistry.References.CopyInto(
openApiDocument.Components.SecuritySchemes);
}
if (documentConfigElement != null)
{
foreach (var documentConfigFilter in _documentConfigFilters)
{
try
{
documentConfigFilter.Apply(
documents,
documentConfigElement,
annotationXmlDocuments,
new DocumentConfigFilterSettings());
}
catch (Exception e)
{
documentGenerationDiagnostic.Errors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
});
}
}
}
var failedOperations = generationDiagnostic.OperationGenerationDiagnostics
.Where(i => i.Errors.Count > 0);
if (failedOperations.Any())
{
var totalOperationsCount = generationDiagnostic.OperationGenerationDiagnostics.Count();
var exception = new UnableToGenerateAllOperationsException(
totalOperationsCount - failedOperations.Count(), totalOperationsCount);
documentGenerationDiagnostic.Errors.Add(
new GenerationError
{
ExceptionType = exception.GetType().Name,
Message = exception.Message
});
}
generationDiagnostic.DocumentGenerationDiagnostic = documentGenerationDiagnostic;
return(documents);
}
catch (Exception e)
{
generationDiagnostic = new GenerationDiagnostic
{
DocumentGenerationDiagnostic =
new DocumentGenerationDiagnostic
{
Errors =
{
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = string.Format(SpecificationGenerationMessages.UnexpectedError, e)
}
}
}
};
return(openApiDocuments);
}
}
