private static void WriteIntroductionDocumentation(StreamWriter writer, DocumentationHeaderSettings headerSettings)
{
writer.WriteLine("documentation: ");
foreach (KeyValuePair<string, string> pair in headerSettings.Introduction)
{
writer.WriteLine(string.Concat(GetIndentString(1), "- title: ", pair.Key));
writer.WriteLine(string.Concat(GetIndentString(2), "content: ", pair.Value));
}
}
private static void WriteIntroductionDocumentation(StreamWriter writer, DocumentationHeaderSettings headerSettings)
{
writer.WriteLine("documentation: ");
foreach (KeyValuePair <string, string> pair in headerSettings.Introduction)
{
writer.WriteLine(string.Concat(GetIndentString(1), "- title: ", pair.Key));
writer.WriteLine(string.Concat(GetIndentString(2), "content: ", pair.Value));
}
}
private void WriteHeader(StreamWriter writer, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore)
{
writer.WriteLine("#%RAML 0.8");
writer.WriteLine("---");
writer.WriteLine(string.Concat("title: ", headerSettings.Title));
writer.WriteLine(string.Concat("version: ", headerSettings.Version));
writer.WriteLine(string.Concat("baseUri: ", headerSettings.BaseURI));
writer.WriteLine(string.Concat("mediaType: ", headerSettings.MediaType));
writer.WriteLine("securedBy: [oauth_2_0]");
WriteSecuritySchemes(writer, headerSettings);
WriteIntroductionDocumentation(writer, headerSettings);
WriteSchemas(writer, schemaStore);
writer.WriteLine();
}
private void WriteDefaultDescription(StreamWriter writer, DocumentationHeaderSettings headerSettings, HttpStatusCode statusCode, int indent)
{
writer.WriteLine(string.Concat(GetIndentString(indent), "description: |"));
writer.WriteLine(string.Concat(GetIndentString(indent + 1), SerialisationUtils.PrettifyHttpStatusCode(statusCode)));
string defaultDescription = null;
headerSettings.DefaultStatusDescriptions.TryGetValue(((int)statusCode).ToString(), out defaultDescription);
if (defaultDescription != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), defaultDescription));
}
else
{
SerialisationLog.Warning(string.Concat("No default description for Http Status Code ", (int)statusCode, ":", statusCode));
}
}
private void WriteSecuritySchemes(StreamWriter writer, DocumentationHeaderSettings headerSettings)
{
writer.WriteLine("securitySchemes:");
writer.WriteLine(string.Concat(GetIndentString(1), "- oauth_2_0:"));
writer.WriteLine(string.Concat(GetIndentString(3), "description: ", headerSettings.OAuth20Description));
writer.WriteLine(string.Concat(GetIndentString(3), "type: OAuth 2.0"));
/*writer.WriteLine(string.Concat(GetIndentString(3), "describedBy:"));
* writer.WriteLine(string.Concat(GetIndentString(4), "responses:"));
* writer.WriteLine(string.Concat(GetIndentString(5), "401:"));
* WriteDefaultDescription(writer, headerSettings, HttpStatusCode.Unauthorized, 6);
* writer.WriteLine(string.Concat(GetIndentString(5), "403:"));
* WriteDefaultDescription(writer, headerSettings, HttpStatusCode.Forbidden, 6);*/
writer.WriteLine(string.Concat(GetIndentString(3), "settings:"));
writer.WriteLine(string.Concat(GetIndentString(4), "accessTokenUri: ", headerSettings.BaseURI, headerSettings.AuthorisationEndpoint));
writer.WriteLine(string.Concat(GetIndentString(4), "authorizationUri: ", headerSettings.BaseURI, headerSettings.AuthorisationEndpoint));
writer.WriteLine(string.Concat(GetIndentString(4), "authorizationGrants: [owner]"));
}
public void Serialise(StreamWriter writer, ResourceNode tree, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore)
{
throw new NotSupportedException();
}
public void Serialise(StreamWriter writer, ResourceNode tree, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore)
{
throw new NotSupportedException();
}
public void Serialise(StreamWriter writer, ResourceNode tree, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore)
{
WriteHeader(writer, headerSettings, schemaStore);
WriteResources(writer, tree, headerSettings, schemaStore, exampleStore, -1);
}
private void WriteSecuritySchemes(StreamWriter writer, DocumentationHeaderSettings headerSettings)
{
writer.WriteLine("securitySchemes:");
writer.WriteLine(string.Concat(GetIndentString(1), "- oauth_2_0:"));
writer.WriteLine(string.Concat(GetIndentString(3), "description: ", headerSettings.OAuth20Description));
writer.WriteLine(string.Concat(GetIndentString(3), "type: OAuth 2.0"));
/*writer.WriteLine(string.Concat(GetIndentString(3), "describedBy:"));
writer.WriteLine(string.Concat(GetIndentString(4), "responses:"));
writer.WriteLine(string.Concat(GetIndentString(5), "401:"));
WriteDefaultDescription(writer, headerSettings, HttpStatusCode.Unauthorized, 6);
writer.WriteLine(string.Concat(GetIndentString(5), "403:"));
WriteDefaultDescription(writer, headerSettings, HttpStatusCode.Forbidden, 6);*/
writer.WriteLine(string.Concat(GetIndentString(3), "settings:"));
writer.WriteLine(string.Concat(GetIndentString(4), "accessTokenUri: ", headerSettings.BaseURI, headerSettings.AuthorisationEndpoint));
writer.WriteLine(string.Concat(GetIndentString(4), "authorizationUri: ", headerSettings.BaseURI, headerSettings.AuthorisationEndpoint));
writer.WriteLine(string.Concat(GetIndentString(4), "authorizationGrants: [owner]"));
}
private void WriteResources(StreamWriter writer, ResourceNode node, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore, int indent)
{
if (node.Parent != null)
{
string key = node.Key;
if (node.Method == null)
{
key = string.Concat("/", key);
}
writer.WriteLine(string.Concat(GetIndentString(indent), key, ":"));
if (node.Class != null && node.HasMethods())
{
// top level resource
RouteDocumentationAttribute attribute = node.Class.GetCustomAttributes<RouteDocumentationAttribute>().Where(a => a.Route != null && a.Route.EndsWith(node.GetRoute())).FirstOrDefault();
if (attribute != null)
{
if (attribute.DisplayName != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "displayName: ", attribute.DisplayName));
}
if (attribute.Summary != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "description: ", attribute.Summary));
}
}
else
{
SerialisationLog.Warning(string.Concat("No route documentation for route '", node.GetRoute(), "' in ", node.Class.Name));
}
}
if (node.Method != null)
{
WriteMethod(writer, node, headerSettings, schemaStore, exampleStore, indent);
}
else if (node.Class != null)
{
NamedParameterDocumentationAttribute attribute = node.Class.GetCustomAttributes<NamedParameterDocumentationAttribute>()
.Where(a => string.Concat("{", a.Name, "}").Equals(node.Key)).FirstOrDefault();
if (attribute != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "uriParameters:"));
writer.WriteLine(string.Concat(GetIndentString(indent + 2), attribute.Name, ":"));
if (attribute.DisplayName != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "displayName: ", attribute.DisplayName));
}
if (attribute.Type != TNamedParameterType.NotSet)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "type: ", attribute.Type.ToString().ToLower()));
}
if (attribute.Description != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "description: ", attribute.Description));
}
}
}
}
foreach (ResourceNode child in node.Children.Values)
{
WriteResources(writer, child, headerSettings, schemaStore, exampleStore, indent + 1);
}
}
private void WriteMethod(StreamWriter writer, ResourceNode node, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore, int indent)
{
MethodDocumentationAttribute attribute = node.Method.GetCustomAttributes<MethodDocumentationAttribute>().FirstOrDefault();
if (node.AllowsAnonymous())
{
string securitySchemes = "null";
if (attribute != null && attribute.AllowMultipleSecuritySchemes)
{
securitySchemes = string.Concat(securitySchemes, ", oauth_2_0");
}
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "securedBy: [", securitySchemes, "]"));
}
if (attribute != null)
{
if (attribute.Summary != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "description: |"));
writer.WriteLine(string.Concat(GetIndentString(indent + 2), attribute.Summary));
Example example = exampleStore.GetExample(node.Class, node.Method, "");
if (example != null)
{
writer.WriteLine(GetIndentString(indent + 2));
writer.WriteLine(string.Concat(GetIndentString(indent + 2), "For more information, go to ", headerSettings.RepositoryFilesURI, "/", example.DocFilename, "#", example.DocHeading));
}
else if (attribute.RequestTypes != null)
{
SerialisationLog.Warning(string.Concat("No example to retrieve link to more information for ", node.Class.Name, ".", node.Method.Name));
}
}
else
{
SerialisationLog.Warning(string.Concat("No summary for ", node.Class.Name, ".", node.Method.Name));
}
if (attribute.ResponseTypes != null && attribute.ResponseTypes.Any(r => r.GetProperties().Any(p => p.PropertyType == typeof(PageInfo))))
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "queryParameters: "));
foreach (KeyValuePair<string, Dictionary<string, string>> field in headerSettings.PagingFields)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 2), field.Key, ":"));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "displayName: ", field.Value["displayName"]));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "description: ", field.Value["description"]));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "type: ", field.Value["type"]));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "required: ", field.Value["required"]));
}
}
if (attribute.RequestTypes != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "body: "));
foreach (Type requestType in attribute.RequestTypes)
{
ContentTypeAttribute contentTypeAttribute = requestType.GetCustomAttributes<ContentTypeAttribute>().FirstOrDefault();
if (contentTypeAttribute == null)
{
SerialisationLog.Warning(string.Concat("No ContentTypeAttribute for ", requestType.FullName));
}
if (attribute.RequestTypeNames != null)
{
foreach (string contentType in attribute.RequestTypeNames)
{
TDataExchangeFormat dataExchangeFormat = SerialisationUtils.GetDataExchangeFormatFromContentType(contentType);
if (dataExchangeFormat != TDataExchangeFormat.None)
{
WriteBody(writer, exampleStore, node, dataExchangeFormat, contentType, TMessageType.Request, requestType, indent + 2);
}
else
{
SerialisationLog.Warning(string.Concat("No supported data exchange format for ", contentType));
}
}
}
else
{
foreach (TDataExchangeFormat dataExchangeFormat in Enum.GetValues(typeof(TDataExchangeFormat)))
{
if (SerialisationUtils.IsStandardDataExchangeFormat(dataExchangeFormat))
{
string contentType = GetContentType(contentTypeAttribute, dataExchangeFormat);
WriteBody(writer, exampleStore, node, dataExchangeFormat, contentType, TMessageType.Request, requestType, indent + 2);
}
}
}
}
}
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "responses:"));
HttpStatusCode[] statusCodes = attribute.StatusCodes;
if (node.Class.GetCustomAttributes<AuthorizeAttribute>().FirstOrDefault() != null)
{
statusCodes = statusCodes.Concat(new[] { HttpStatusCode.Unauthorized, HttpStatusCode.Forbidden }).ToArray();
}
foreach (HttpStatusCode statusCode in statusCodes)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 2), (int)statusCode, ":"));
WriteDefaultDescription(writer, headerSettings, statusCode, indent + 3);
if (SerialisationUtils.IsSuccessStatusCode(statusCode) && attribute.ResponseTypes != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "body:"));
foreach (Type responseType in attribute.ResponseTypes)
{
ContentTypeAttribute contentTypeAttribute = responseType.GetCustomAttributes<ContentTypeAttribute>().FirstOrDefault();
if (contentTypeAttribute == null)
{
SerialisationLog.Warning(string.Concat("No ContentTypeAttribute for ", responseType.FullName));
}
foreach (TDataExchangeFormat dataExchangeFormat in Enum.GetValues(typeof(TDataExchangeFormat)))
{
if (SerialisationUtils.IsStandardDataExchangeFormat(dataExchangeFormat))
{
string contentType = GetContentType(contentTypeAttribute, dataExchangeFormat);
WriteBody(writer, exampleStore, node, dataExchangeFormat, contentType, TMessageType.Response, responseType, indent + 4);
}
}
}
}
}
}
else
{
SerialisationLog.Warning(string.Concat("No method-level documentation for ", node.Class.Name, ".", node.Method.Name));
}
}
private void WriteHeader(StreamWriter writer, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore)
{
writer.WriteLine("#%RAML 0.8");
writer.WriteLine("---");
writer.WriteLine(string.Concat("title: ", headerSettings.Title));
writer.WriteLine(string.Concat("version: ", headerSettings.Version));
writer.WriteLine(string.Concat("baseUri: ", headerSettings.BaseURI));
writer.WriteLine(string.Concat("mediaType: ", headerSettings.MediaType));
writer.WriteLine("securedBy: [oauth_2_0]");
WriteSecuritySchemes(writer, headerSettings);
WriteIntroductionDocumentation(writer, headerSettings);
WriteSchemas(writer, schemaStore);
writer.WriteLine();
}
private void WriteDefaultDescription(StreamWriter writer, DocumentationHeaderSettings headerSettings, HttpStatusCode statusCode, int indent)
{
writer.WriteLine(string.Concat(GetIndentString(indent), "description: |"));
writer.WriteLine(string.Concat(GetIndentString(indent + 1), SerialisationUtils.PrettifyHttpStatusCode(statusCode)));
string defaultDescription = null;
headerSettings.DefaultStatusDescriptions.TryGetValue(((int)statusCode).ToString(), out defaultDescription);
if (defaultDescription != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), defaultDescription));
}
else
{
SerialisationLog.Warning(string.Concat("No default description for Http Status Code ", (int)statusCode, ":", statusCode));
}
}
public void Serialise(StreamWriter writer, ResourceNode tree, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore)
{
WriteHeader(writer, headerSettings, schemaStore);
WriteResources(writer, tree, headerSettings, schemaStore, exampleStore, -1);
}
private void WriteMethod(StreamWriter writer, ResourceNode node, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore, int indent)
{
MethodDocumentationAttribute attribute = node.Method.GetCustomAttributes <MethodDocumentationAttribute>().FirstOrDefault();
if (node.AllowsAnonymous())
{
string securitySchemes = "null";
if (attribute != null && attribute.AllowMultipleSecuritySchemes)
{
securitySchemes = string.Concat(securitySchemes, ", oauth_2_0");
}
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "securedBy: [", securitySchemes, "]"));
}
if (attribute != null)
{
if (attribute.Summary != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "description: |"));
writer.WriteLine(string.Concat(GetIndentString(indent + 2), attribute.Summary));
Example example = exampleStore.GetExample(node.Class, node.Method, "");
if (example != null)
{
writer.WriteLine(GetIndentString(indent + 2));
writer.WriteLine(string.Concat(GetIndentString(indent + 2), "For more information, go to ", headerSettings.RepositoryFilesURI, "/", example.DocFilename, "#", example.DocHeading));
}
else if (attribute.RequestTypes != null)
{
SerialisationLog.Warning(string.Concat("No example to retrieve link to more information for ", node.Class.Name, ".", node.Method.Name));
}
}
else
{
SerialisationLog.Warning(string.Concat("No summary for ", node.Class.Name, ".", node.Method.Name));
}
if (attribute.ResponseTypes != null && attribute.ResponseTypes.Any(r => r.GetProperties().Any(p => p.PropertyType == typeof(PageInfo))))
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "queryParameters: "));
foreach (KeyValuePair <string, Dictionary <string, string> > field in headerSettings.PagingFields)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 2), field.Key, ":"));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "displayName: ", field.Value["displayName"]));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "description: ", field.Value["description"]));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "type: ", field.Value["type"]));
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "required: ", field.Value["required"]));
}
}
if (attribute.RequestTypes != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "body: "));
foreach (Type requestType in attribute.RequestTypes)
{
ContentTypeAttribute contentTypeAttribute = requestType.GetCustomAttributes <ContentTypeAttribute>().FirstOrDefault();
if (contentTypeAttribute == null)
{
SerialisationLog.Warning(string.Concat("No ContentTypeAttribute for ", requestType.FullName));
}
if (attribute.RequestTypeNames != null)
{
foreach (string contentType in attribute.RequestTypeNames)
{
TDataExchangeFormat dataExchangeFormat = SerialisationUtils.GetDataExchangeFormatFromContentType(contentType);
if (dataExchangeFormat != TDataExchangeFormat.None)
{
WriteBody(writer, exampleStore, node, dataExchangeFormat, contentType, TMessageType.Request, requestType, indent + 2);
}
else
{
SerialisationLog.Warning(string.Concat("No supported data exchange format for ", contentType));
}
}
}
else
{
foreach (TDataExchangeFormat dataExchangeFormat in Enum.GetValues(typeof(TDataExchangeFormat)))
{
if (SerialisationUtils.IsStandardDataExchangeFormat(dataExchangeFormat))
{
string contentType = GetContentType(contentTypeAttribute, dataExchangeFormat);
WriteBody(writer, exampleStore, node, dataExchangeFormat, contentType, TMessageType.Request, requestType, indent + 2);
}
}
}
}
}
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "responses:"));
HttpStatusCode[] statusCodes = attribute.StatusCodes;
if (node.Class.GetCustomAttributes <AuthorizeAttribute>().FirstOrDefault() != null)
{
statusCodes = statusCodes.Concat(new[] { HttpStatusCode.Unauthorized, HttpStatusCode.Forbidden }).ToArray();
}
foreach (HttpStatusCode statusCode in statusCodes)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 2), (int)statusCode, ":"));
WriteDefaultDescription(writer, headerSettings, statusCode, indent + 3);
if (SerialisationUtils.IsSuccessStatusCode(statusCode) && attribute.ResponseTypes != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "body:"));
foreach (Type responseType in attribute.ResponseTypes)
{
ContentTypeAttribute contentTypeAttribute = responseType.GetCustomAttributes <ContentTypeAttribute>().FirstOrDefault();
if (contentTypeAttribute == null)
{
SerialisationLog.Warning(string.Concat("No ContentTypeAttribute for ", responseType.FullName));
}
foreach (TDataExchangeFormat dataExchangeFormat in Enum.GetValues(typeof(TDataExchangeFormat)))
{
if (SerialisationUtils.IsStandardDataExchangeFormat(dataExchangeFormat))
{
string contentType = GetContentType(contentTypeAttribute, dataExchangeFormat);
WriteBody(writer, exampleStore, node, dataExchangeFormat, contentType, TMessageType.Response, responseType, indent + 4);
}
}
}
}
}
}
else
{
SerialisationLog.Warning(string.Concat("No method-level documentation for ", node.Class.Name, ".", node.Method.Name));
}
}
private void WriteResources(StreamWriter writer, ResourceNode node, DocumentationHeaderSettings headerSettings, SchemaStore schemaStore, ExampleStore exampleStore, int indent)
{
if (node.Parent != null)
{
string key = node.Key;
if (node.Method == null)
{
key = string.Concat("/", key);
}
writer.WriteLine(string.Concat(GetIndentString(indent), key, ":"));
if (node.Class != null && node.HasMethods())
{
// top level resource
RouteDocumentationAttribute attribute = node.Class.GetCustomAttributes <RouteDocumentationAttribute>().Where(a => a.Route != null && a.Route.EndsWith(node.GetRoute())).FirstOrDefault();
if (attribute != null)
{
if (attribute.DisplayName != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "displayName: ", attribute.DisplayName));
}
if (attribute.Summary != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "description: ", attribute.Summary));
}
}
else
{
SerialisationLog.Warning(string.Concat("No route documentation for route '", node.GetRoute(), "' in ", node.Class.Name));
}
}
if (node.Method != null)
{
WriteMethod(writer, node, headerSettings, schemaStore, exampleStore, indent);
}
else if (node.Class != null)
{
NamedParameterDocumentationAttribute attribute = node.Class.GetCustomAttributes <NamedParameterDocumentationAttribute>()
.Where(a => string.Concat("{", a.Name, "}").Equals(node.Key)).FirstOrDefault();
if (attribute != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 1), "uriParameters:"));
writer.WriteLine(string.Concat(GetIndentString(indent + 2), attribute.Name, ":"));
if (attribute.DisplayName != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "displayName: ", attribute.DisplayName));
}
if (attribute.Type != TNamedParameterType.NotSet)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "type: ", attribute.Type.ToString().ToLower()));
}
if (attribute.Description != null)
{
writer.WriteLine(string.Concat(GetIndentString(indent + 3), "description: ", attribute.Description));
}
}
}
}
foreach (ResourceNode child in node.Children.Values)
{
WriteResources(writer, child, headerSettings, schemaStore, exampleStore, indent + 1);
}
}
