/// <summary>
/// Initializes a new instance of the <see cref="ConflictingDocumentVariantAttributesException"/> class.
/// </summary>
/// <param name="existingDocumentVariantInfo">The existing document variant info.</param>
/// <param name="newDocumentVariantInfo">The new equivalent document variant info but with different attributes.</param>
public ConflictingDocumentVariantAttributesException(
DocumentVariantInfo existingDocumentVariantInfo,
DocumentVariantInfo newDocumentVariantInfo)
: base(
string.Format(
SpecificationGenerationMessages.ConflictingDocumentVariantAttributes,
existingDocumentVariantInfo.Categorizer,
existingDocumentVariantInfo.Title,
existingDocumentVariantInfo.Attributes.ToSerializedString(),
newDocumentVariantInfo.Attributes.ToSerializedString()))
{
}
private void PopulateAttributesInExistingDocumentVariantInfo(
IDictionary <DocumentVariantInfo, OpenApiDocument> documents,
DocumentVariantInfo documentVariantInfo)
{
foreach (var existingDocumentVariantInfo in documents.Keys)
{
if (!documentVariantInfo.Attributes.Any())
{
// If the new document variant info has no attributes, simply ignore and move on to
// the next document variant info.
continue;
}
if (!existingDocumentVariantInfo.Equals(documentVariantInfo))
{
// If the document variant infos are not equal, we can move on to the next one.
continue;
}
if (!existingDocumentVariantInfo.Attributes.Any())
{
// If the existing document variant info has no attributes, simply point its Attributes
// to the Attributes in the new document variant info.
existingDocumentVariantInfo.Attributes = documentVariantInfo.Attributes;
break;
}
if (!existingDocumentVariantInfo.AreAttributesEquivalent(documentVariantInfo))
{
// If the attributes are present in the existing document variant info but they
// are not equivalent to the new one, there is a conflict.
throw new ConflictingDocumentVariantAttributesException(
existingDocumentVariantInfo,
documentVariantInfo);
}
}
}
/// <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>
/// Populate the specification documents for all document variant infos.
/// </summary>
/// <returns>The operation generation results from populating the specification documents.</returns>
private IList <OperationGenerationDiagnostic> GenerateSpecificationDocuments(
TypeFetcher typeFetcher,
IList <XElement> operationElements,
XElement operationConfigElement,
string documentVariantElementName,
out IDictionary <DocumentVariantInfo, OpenApiDocument> specificationDocuments)
{
specificationDocuments = new Dictionary <DocumentVariantInfo, OpenApiDocument>();
var operationGenerationResults = new List <OperationGenerationDiagnostic>();
var referenceRegistryManagerMap = new Dictionary <DocumentVariantInfo, ReferenceRegistryManager>();
foreach (var operationElement in operationElements)
{
string url;
OperationType operationMethod;
try
{
url = OperationHandler.GetUrl(operationElement);
}
catch (InvalidUrlException e)
{
operationGenerationResults.Add(
new OperationGenerationDiagnostic
{
Errors =
{
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
},
OperationMethod = SpecificationGenerationMessages.OperationMethodNotParsedGivenUrlIsInvalid,
Path = e.Url
});
continue;
}
try
{
operationMethod = OperationHandler.GetOperationMethod(url, operationElement);
}
catch (InvalidVerbException e)
{
operationGenerationResults.Add(
new OperationGenerationDiagnostic
{
Errors =
{
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
},
OperationMethod = e.Verb,
Path = url
});
continue;
}
var operationGenerationErrors = new List <GenerationError>();
try
{
AddOperation(
specificationDocuments,
referenceRegistryManagerMap,
operationGenerationErrors,
DocumentVariantInfo.Default,
operationElement,
operationConfigElement,
typeFetcher);
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
});
}
var customElements = operationElement.Descendants(documentVariantElementName);
foreach (var customElement in customElements)
{
try
{
var documentVariantInfo = new DocumentVariantInfo
{
Categorizer = customElement.Name.LocalName.Trim(),
Title = customElement.Value.Trim()
};
AddOperation(
specificationDocuments,
referenceRegistryManagerMap,
operationGenerationErrors,
documentVariantInfo,
operationElement,
operationConfigElement,
typeFetcher);
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
});
}
}
var operationGenerationResult = new OperationGenerationDiagnostic
{
OperationMethod = operationMethod.ToString(),
Path = url
};
if (operationGenerationErrors.Any())
{
foreach (var error in operationGenerationErrors)
{
operationGenerationResult.Errors.Add(new GenerationError(error));
}
}
operationGenerationResults.Add(operationGenerationResult);
}
foreach (var documentVariantInfo in specificationDocuments.Keys)
{
referenceRegistryManagerMap[documentVariantInfo]
.SchemaReferenceRegistry.References.CopyInto(
specificationDocuments[documentVariantInfo].Components.Schemas);
}
return(operationGenerationResults);
}
/// <summary>
/// Builds <see cref="InternalGenerationContext"/> by reflecting into contract assemblies.
/// </summary>
/// <param name="contractAssembliesPaths">The contract assemlby paths.</param>
/// <param name="operationElements">The operation xelements.</param>
/// <param name="propertyElements">The property xelements</param>
/// <param name="documentVariantElementName">The document variant element name.</param>
/// <param name="internalSchemaGenerationSettings"><see cref="InternalSchemaGenerationSettings"/></param>
/// <returns>Serialized <see cref="InternalGenerationContext"/></returns>
public string BuildInternalGenerationContext(
IList <string> contractAssembliesPaths,
IList <string> operationElements,
IList <string> propertyElements,
string documentVariantElementName,
InternalSchemaGenerationSettings internalSchemaGenerationSettings)
{
var crefSchemaMap = new Dictionary <string, InternalSchemaGenerationInfo>();
List <XElement> xPropertyElements = propertyElements.Select(XElement.Parse).ToList();
var propertyMap = new Dictionary <string, string>();
foreach (var xPropertyElement in xPropertyElements)
{
var name = xPropertyElement
.Attributes(KnownXmlStrings.Name)?.FirstOrDefault()?.Value?.Split(':')[1];
var description = xPropertyElement.Element(KnownXmlStrings.Summary)?.Value.RemoveBlankLines();
if (!propertyMap.ContainsKey(name))
{
propertyMap.Add(name, description);
}
}
var referenceRegistryMap = new Dictionary <DocumentVariantInfo, SchemaReferenceRegistry>();
var schemaGenerationSettings = new SchemaGenerationSettings(new DefaultPropertyNameResolver());
if (internalSchemaGenerationSettings.PropertyNameResolverName ==
typeof(CamelCasePropertyNameResolver).FullName)
{
schemaGenerationSettings = new SchemaGenerationSettings(new CamelCasePropertyNameResolver());
}
var internalGenerationContext = new InternalGenerationContext();
#if !NETFRAMEWORK
var typeFetcher = new TypeFetcher(contractAssembliesPaths, Context);
#else
var typeFetcher = new TypeFetcher(contractAssembliesPaths);
#endif
List <XElement> xOperationElements = operationElements.Select(XElement.Parse).ToList();
foreach (var xOperationElement in xOperationElements)
{
if (!referenceRegistryMap.ContainsKey(DocumentVariantInfo.Default))
{
referenceRegistryMap.Add(
DocumentVariantInfo.Default,
new SchemaReferenceRegistry(schemaGenerationSettings, propertyMap));
}
// Recursively build the various cref-schema, cref-fieldValue map.
BuildMap(
xOperationElement,
crefSchemaMap,
internalGenerationContext.CrefToFieldValueMap,
typeFetcher,
referenceRegistryMap[DocumentVariantInfo.Default]);
var customElements = xOperationElement.Descendants(documentVariantElementName);
// Build the various cref-schema, cref-fieldValue map for each customElement.
foreach (var customElement in customElements)
{
var documentVariantInfo = new DocumentVariantInfo
{
Categorizer = customElement.Name.LocalName.Trim(),
Title = customElement.Value.Trim()
};
if (!referenceRegistryMap.ContainsKey(documentVariantInfo))
{
referenceRegistryMap.Add(
documentVariantInfo,
new SchemaReferenceRegistry(schemaGenerationSettings, propertyMap));
}
BuildMap(
xOperationElement,
crefSchemaMap,
internalGenerationContext.CrefToFieldValueMap,
typeFetcher,
referenceRegistryMap[documentVariantInfo]);
}
}
foreach (var key in referenceRegistryMap.Keys)
{
var references = referenceRegistryMap[key].References;
internalGenerationContext.VariantSchemaReferenceMap.Add(
key.ToString(),
references.ToDictionary(k => k.Key, k => k.Value.SerializeAsJson(OpenApiSpecVersion.OpenApi3_0)));
}
internalGenerationContext.CrefToSchemaMap = crefSchemaMap;
// Serialize the context to transfer across app domain.
var document = JsonConvert.SerializeObject(internalGenerationContext);
return(document);
}
/// <summary>
/// Fetches the attributes in document variant option as well as the entire documentation itself
/// and populate the document variant info objects.
/// </summary>
/// <param name="documents">The documents to be updated.</param>
/// <param name="element">The xml element containing document-level config in the config xml.</param>
/// <param name="xmlDocuments">The list of XDocuments representing the annotation xmls.</param>
/// <param name="settings">The document config filter settings.</param>
/// <exception cref="ConflictingDocumentVariantAttributesException">
/// Thrown when there is a conflict
/// between the attributes in the existing document variant info and the new one.
/// </exception>
public void Apply(
IDictionary <DocumentVariantInfo, OpenApiDocument> documents,
XElement element,
IList <XDocument> xmlDocuments,
DocumentConfigFilterSettings settings)
{
var variantElements = element.Elements(KnownXmlStrings.Variant);
foreach (var variantElement in variantElements)
{
// First, populate the document variant info attributes using the document variant option.
var variantOptions = variantElement.Element(KnownXmlStrings.Options)?.Elements(KnownXmlStrings.Option);
if (variantOptions != null)
{
foreach (var variantOption in variantOptions)
{
var documentVariantInfo = new DocumentVariantInfo
{
Title = variantOption.Value,
Categorizer = variantElement.Element(KnownXmlStrings.Name)?.Value
};
foreach (var attribute in variantOption.Attributes())
{
if (!documentVariantInfo.Attributes.ContainsKey(attribute.Name.ToString()))
{
documentVariantInfo.Attributes[attribute.Name.ToString()] = attribute.Value;
}
}
PopulateAttributesInExistingDocumentVariantInfo(documents, documentVariantInfo);
}
}
// Second, populate the document variant info attributes using the information from the documents.
var allCategorizerNodes = new List <XElement>();
foreach (var xmlDocument in xmlDocuments)
{
allCategorizerNodes.AddRange(
xmlDocument.Descendants(variantElement.Element(KnownXmlStrings.Name)?.Value));
}
foreach (var categorizerNode in allCategorizerNodes)
{
var documentVariantInfo = new DocumentVariantInfo
{
Title = categorizerNode.Value,
Categorizer = categorizerNode.Name.ToString()
};
foreach (var attribute in categorizerNode.Attributes())
{
if (!documentVariantInfo.Attributes.ContainsKey(attribute.Name.ToString()))
{
documentVariantInfo.Attributes[attribute.Name.ToString()] = attribute.Value;
}
}
PopulateAttributesInExistingDocumentVariantInfo(documents, documentVariantInfo);
}
}
}
/// <summary>
/// Fetches the attributes in document variant option as well as the entire documentation itself
/// and populate the document variant info objects.
/// </summary>
/// <param name="documents">The documents to be updated.</param>
/// <param name="element">The xml element containing document-level config in the config xml.</param>
/// <param name="xmlDocuments">The list of XDocuments representing the annotation xmls.</param>
/// <param name="settings">The document config filter settings.</param>
/// <exception cref="ConflictingDocumentVariantAttributesException">
/// Thrown when there is a conflict
/// between the attributes in the existing document variant info and the new one.
/// </exception>
/// <returns>The list of generation errors, if any produced when processing the filter.</returns>
public IList <GenerationError> Apply(
IDictionary <DocumentVariantInfo, OpenApiDocument> documents,
XElement element,
IList <XDocument> xmlDocuments,
DocumentConfigFilterSettings settings)
{
var generationErrors = new List <GenerationError>();
if (element == null || xmlDocuments == null)
{
return(generationErrors);
}
try
{
var variantElements = element.Elements(KnownXmlStrings.Variant);
foreach (var variantElement in variantElements)
{
// First, populate the document variant info attributes using the document variant option.
var variantOptions = variantElement.Element(KnownXmlStrings.Options)?.Elements(KnownXmlStrings.Option);
if (variantOptions != null)
{
foreach (var variantOption in variantOptions)
{
var documentVariantInfo = new DocumentVariantInfo
{
Title = variantOption.Value,
Categorizer = variantElement.Element(KnownXmlStrings.Name)?.Value
};
foreach (var attribute in variantOption.Attributes())
{
if (!documentVariantInfo.Attributes.ContainsKey(attribute.Name.ToString()))
{
documentVariantInfo.Attributes[attribute.Name.ToString()] = attribute.Value;
}
}
PopulateAttributesInExistingDocumentVariantInfo(documents, documentVariantInfo);
}
}
// Second, populate the document variant info attributes using the information from the documents.
var allCategorizerNodes = new List <XElement>();
foreach (var xmlDocument in xmlDocuments)
{
allCategorizerNodes.AddRange(
xmlDocument.Descendants(variantElement.Element(KnownXmlStrings.Name)?.Value));
}
foreach (var categorizerNode in allCategorizerNodes)
{
var documentVariantInfo = new DocumentVariantInfo
{
Title = categorizerNode.Value,
Categorizer = categorizerNode.Name.ToString()
};
foreach (var attribute in categorizerNode.Attributes())
{
if (!documentVariantInfo.Attributes.ContainsKey(attribute.Name.ToString()))
{
documentVariantInfo.Attributes[attribute.Name.ToString()] = attribute.Value;
}
}
PopulateAttributesInExistingDocumentVariantInfo(documents, documentVariantInfo);
}
}
}
catch (Exception ex)
{
generationErrors.Add(
new GenerationError
{
Message = ex.Message,
ExceptionType = ex.GetType().Name
});
}
return(generationErrors);
}
/// <summary>
/// Populate the specification documents for all document variant infos.
/// </summary>
/// <returns>The operation generation results from populating the specification documents.</returns>
private IList <OperationGenerationDiagnostic> GenerateSpecificationDocuments(
GenerationContext generationContext,
IList <XElement> operationElements,
XElement operationConfigElement,
string documentVariantElementName,
out IDictionary <DocumentVariantInfo, OpenApiDocument> specificationDocuments)
{
specificationDocuments = new Dictionary <DocumentVariantInfo, OpenApiDocument>();
var operationGenerationResults = new List <OperationGenerationDiagnostic>();
var referenceRegistryManagerMap = new Dictionary <DocumentVariantInfo, ReferenceRegistryManager>();
foreach (var operationElement in operationElements)
{
string url;
OperationType operationMethod;
OperationType operationMethod1 = OperationType.Trace;
try
{
url = OperationHandler.GetUrl(operationElement);
}
catch (InvalidUrlException e)
{
operationGenerationResults.Add(
new OperationGenerationDiagnostic
{
Errors =
{
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
},
OperationMethod = SpecificationGenerationMessages.OperationMethodNotParsedGivenUrlIsInvalid,
Path = e.Url
});
continue;
}
bool doubleverb = false;
try
{
string safe = OperationHandler.GetOperationMethod(url, operationElement);
if (safe.Contains('/'))
{
string[] split = safe.Split('/');
doubleverb = true;
Enum.TryParse(split[0], true, out operationMethod);
Enum.TryParse(split[1], true, out operationMethod1);
}
else
{
Enum.TryParse(safe, true, out operationMethod);
}
}
catch (InvalidVerbException e)
{
operationGenerationResults.Add(
new OperationGenerationDiagnostic
{
Errors =
{
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
}
},
OperationMethod = e.Verb,
Path = url
});
continue;
}
var operationGenerationErrors = new List <GenerationError>();
try
{
AddOperation(
specificationDocuments,
referenceRegistryManagerMap,
operationGenerationErrors,
DocumentVariantInfo.Default,
operationElement,
operationConfigElement,
generationContext);
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
});
}
var customElements = operationElement.Descendants(documentVariantElementName);
foreach (var customElement in customElements)
{
try
{
var documentVariantInfo = new DocumentVariantInfo
{
Categorizer = customElement.Name.LocalName.Trim(),
Title = customElement.Value.Trim()
};
AddOperation(
specificationDocuments,
referenceRegistryManagerMap,
operationGenerationErrors,
documentVariantInfo,
operationElement,
operationConfigElement,
generationContext);
}
catch (Exception e)
{
operationGenerationErrors.Add(
new GenerationError
{
ExceptionType = e.GetType().Name,
Message = e.Message
});
}
}
if (doubleverb)
{
doubleverb = false;
var operationGenerationResult = new OperationGenerationDiagnostic
{
OperationMethod = operationMethod.ToString(),
Path = url
};
var operationGenerationResult1 = new OperationGenerationDiagnostic
{
OperationMethod = operationMethod1.ToString(),
Path = url
};
if (operationGenerationErrors.Any())
{
foreach (var error in operationGenerationErrors)
{
operationGenerationResult.Errors.Add(new GenerationError(error));
}
}
operationGenerationResults.Add(operationGenerationResult);
operationGenerationResults.Add(operationGenerationResult1);
}
else
{
var operationGenerationResult = new OperationGenerationDiagnostic
{
OperationMethod = operationMethod.ToString(),
Path = url
};
if (operationGenerationErrors.Any())
{
foreach (var error in operationGenerationErrors)
{
operationGenerationResult.Errors.Add(new GenerationError(error));
}
}
operationGenerationResults.Add(operationGenerationResult);
}
}
foreach (var documentVariantInfo in generationContext.VariantSchemaReferenceMap.Keys)
{
var references = generationContext.VariantSchemaReferenceMap[documentVariantInfo].ToDictionary(
k => k.Key,
k => k.Value);
if (specificationDocuments.ContainsKey(documentVariantInfo))
{
references.CopyInto(specificationDocuments[documentVariantInfo].Components.Schemas);
}
}
foreach (var documentVariantInfo in specificationDocuments.Keys)
{
referenceRegistryManagerMap[documentVariantInfo]
.SecuritySchemeReferenceRegistry.References.CopyInto(
specificationDocuments[documentVariantInfo].Components.SecuritySchemes);
}
return(operationGenerationResults);
}
