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 WriteExample(StreamWriter writer, ExampleStore exampleStore, Type classType, MethodInfo methodInfo, string contentType, TMessageType exampleType, TDataExchangeFormat dataExchangeFormat, int indent) { string exampleText = exampleStore.GetExampleContent(classType, methodInfo, exampleType, contentType, dataExchangeFormat); if (exampleText != null) { writer.WriteLine(string.Concat(GetIndentString(indent), "example: |")); List <string> lines = SerialisationUtils.SplitLines(exampleText); foreach (string line in lines) { writer.WriteLine(string.Concat(GetIndentString(indent + 1), line)); } } else if (dataExchangeFormat != TDataExchangeFormat.Xml) { SerialisationLog.Warning(string.Concat("No example for ", classType.Name, ".", methodInfo.Name, " ", dataExchangeFormat, " ", exampleType.ToString().ToLower())); } }
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); } }