/// <summary>
/// Writes the API HTML document.
/// </summary>
/// <param name="builder">The builder.</param>
/// <param name="apiServiceType">Type of the API service.</param>
/// <param name="apiContractOptions">The API contract options.</param>
/// <param name="classTokenRequiredAttribute">The class token required attribute.</param>
/// <param name="enumSets">The enum sets.</param>
protected void WriteApiHtmlDocument(StringBuilder builder, Type apiServiceType, IApiContractOptions apiContractOptions, TokenRequiredAttribute classTokenRequiredAttribute, HashSet <Type> enumSets)
{
if (builder != null && apiServiceType != null && apiContractOptions != null)
{
foreach (MethodInfo one in apiServiceType.GetMethodInfoWithinAttribute <ApiOperationAttribute>(true, BindingFlags.Instance | BindingFlags.Public))
{
// Considering in interface, can NOT tell is async or not, check return type is Task or Task<T>.
bool isAsync = one.IsAsync() || one.ReturnType.IsTask();
var apiOperationAttribute = one.GetCustomAttribute <ApiOperationAttribute>(true);
if (apiOperationAttribute != null)
{
StringBuilder bodyBuilder = new StringBuilder(4096);
#region Entity Synchronization Status
var entitySynchronizationAttribute = one.GetCustomAttribute <EntitySynchronizationModeAttribute>(true);
if (entitySynchronizationAttribute != null && !EntitySynchronizationModeAttribute.IsReturnTypeMatched(one.ReturnType))
{
entitySynchronizationAttribute = null;
}
#endregion Entity Synchronization Status
//Original declaration
bodyBuilder.Append("<h3>.NET Declaration</h3>");
bodyBuilder.AppendFormat(isAsync ? "<div><span style=\"color:red;font-weight:bold;\" title=\"Async\">[A] </span> {0}</div>" : "<div>{0}</div>", one.ToDeclarationCodeLook().ToHtmlEncodedText());
bodyBuilder.Append("<hr />");
//Try append description
var apiDescriptionAttributes = one.GetCustomAttributes <ApiDescriptionAttribute>(true);
if (apiDescriptionAttributes != null && apiDescriptionAttributes.Any())
{
foreach (var description in apiDescriptionAttributes)
{
if (!string.IsNullOrWhiteSpace(description.Description))
{
bodyBuilder.AppendFormat("<div>{0}</div>", description.Description.ToHtmlEncodedText());
}
}
}
// Customized headers
var apiCustomizedHeaderAttributes = one.GetCustomAttributes <ApiHeaderAttribute>(true);
if (apiCustomizedHeaderAttributes.HasItem())
{
bodyBuilder.Append("<h3>Customized headers</h3><hr />");
bodyBuilder.Append("<ul>");
foreach (var item in apiCustomizedHeaderAttributes)
{
bodyBuilder.AppendFormat(customHeaderFormat, item.HeaderKey);
}
bodyBuilder.Append("</ul>");
}
var obsolete = one.GetCustomAttribute <ObsoleteAttribute>(true);
if (obsolete != null)
{
bodyBuilder.AppendFormat("<div style=\"color:red;\"> Obsoleted: {0}</div>", obsolete.Message.ToHtmlEncodedText());
}
bodyBuilder.Append("<div>Following sample shows how to use via REST API.</div>");
#region Request
bodyBuilder.Append("<h3>Request</h3><hr />");
bodyBuilder.Append("<url>");
if (string.IsNullOrWhiteSpace(apiContractOptions.Realm))
{
bodyBuilder.AppendFormat("{0} /api/{1}/{2}/", apiOperationAttribute.HttpMethod, apiContractOptions.Version, apiOperationAttribute.ResourceName);
}
else
{
bodyBuilder.AppendFormat("{0} /{1}/api/{2}/{3}/", apiContractOptions.Realm, apiOperationAttribute.HttpMethod, apiContractOptions.Version, apiOperationAttribute.ResourceName);
}
if (!string.IsNullOrWhiteSpace(apiOperationAttribute.Action))
{
bodyBuilder.AppendFormat("{0}/", apiOperationAttribute.Action);
}
var parameters = one.GetParameters();
var parameterIsHandled = false;
if (parameters.Length == 0)
{
parameterIsHandled = true;
}
else if (parameters.Length == 1 && (apiOperationAttribute.HttpMethod.Equals(HttpConstants.HttpMethod.Get, StringComparison.OrdinalIgnoreCase) ||
apiOperationAttribute.HttpMethod.Equals(HttpConstants.HttpMethod.Delete, StringComparison.OrdinalIgnoreCase)))
{
if (parameters[0].ParameterType == typeof(string) || parameters[0].ParameterType.IsValueType)
{
bodyBuilder.AppendFormat("<span style=\"font-style:italic; font-weight:bold;color:#CC0000;\" title=\"Sample value for {0}\">", parameters[0].Name);
FillSampleValue(bodyBuilder, parameters[0].ParameterType, enumSets, 0, fieldName: parameters[0].Name, ignoreQuote: true);
bodyBuilder.Append("</span>");
parameterIsHandled = true;
}
}
else if (parameters.Length > 1 && (apiOperationAttribute.HttpMethod.Equals(HttpConstants.HttpMethod.Get, StringComparison.OrdinalIgnoreCase) ||
apiOperationAttribute.HttpMethod.Equals(HttpConstants.HttpMethod.Delete, StringComparison.OrdinalIgnoreCase)))
{
bodyBuilder.Append("?");
foreach (var parameterItem in parameters)
{
bodyBuilder.AppendFormat("{0}=", parameterItem.Name);
FillSampleValue(bodyBuilder, parameterItem.ParameterType, enumSets, 0, parameterItem.Name, true, true);
bodyBuilder.Append("&");
}
bodyBuilder.RemoveLastIfMatch('&', true);
parameterIsHandled = true;
}
bodyBuilder.Append("</url>");
var currentTokenRequiredAttribute = one.GetCustomAttribute <TokenRequiredAttribute>(true) ?? classTokenRequiredAttribute;
if (currentTokenRequiredAttribute != null && currentTokenRequiredAttribute.TokenRequired)
{
bodyBuilder.AppendLineWithFormat(requestHeaderFormat, TokenKey, "[YourTokenValue]");
}
if (entitySynchronizationAttribute != null)
{
bodyBuilder.AppendLineWithFormat(requestHeaderFormat, entitySynchronizationAttribute.IfModifiedSinceKey, DateTime.UtcNow.AddDays(-2).ToFullDateTimeString());
}
bodyBuilder.Append("<pre class=\"CodeContainer\" style=\"font-family: monospace;font-size:14px;\">");
if (!parameterIsHandled)
{
if (parameters.Length == 1)
{
FillSampleValue(bodyBuilder, parameters[0].ParameterType, enumSets, 0, fieldName: parameters[0].Name, followingProperty: false);
}
else
{
builder.AppendFormat(objectBrace, "{");
foreach (var parameterItem in parameters)
{
FillProperty(bodyBuilder, parameterItem.Name, parameterItem.ParameterType);
AppendColon(bodyBuilder);
FillSampleValue(bodyBuilder, parameterItem.ParameterType, enumSets, 1, followingProperty: true);
AppendComma(bodyBuilder);
}
RemoveUnnecessaryColon(bodyBuilder);
bodyBuilder.AppendFormat(objectBrace, "}");
}
}
bodyBuilder.Append("</pre>");
#endregion Request
#region Response
bodyBuilder.Append("<h3>Response</h3><hr />");
bodyBuilder.AppendLineWithFormat(requestHeaderFormat, HttpConstants.HttpHeader.ContentType, apiOperationAttribute.ContentType.SafeToString(HttpConstants.ContentType.Json));
if (entitySynchronizationAttribute != null)
{
bodyBuilder.AppendLineWithFormat(requestHeaderFormat, entitySynchronizationAttribute.LastModifiedKey, DateTime.UtcNow.ToFullDateTimeString());
}
bodyBuilder.Append("<pre class=\"CodeContainer\" style=\"font-family: monospace;font-size:14px;\">");
var returnType = one.ReturnType;
if (isAsync)
{
returnType = returnType.GetTaskUnderlyingType() ?? returnType;
}
if (returnType.IsVoid() ?? true)
{
bodyBuilder.Append("<span style=\"font-style:italic; font-weight: bold; color: #999999;\">void</span>");
}
else
{
FillSampleValue(bodyBuilder, returnType, enumSets, 0);
}
bodyBuilder.Append("</pre>");
#endregion Response
#region Http Status
// Http Status
bodyBuilder.Append("<h3>Http Status & Exceptions</h3><hr />");
bodyBuilder.Append("<ul>");
if (one.ReturnType.IsVoid() ?? false)
{
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.NoContent, HttpStatusCode.NoContent.ToString(), "If no error or exception.", "green");
}
else
{
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.OK, HttpStatusCode.OK.ToString(), "If no error or exception.", "green");
if (entitySynchronizationAttribute != null)
{
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.NotModified, HttpStatusCode.NotModified.ToString(), "If no modified since specific time stamp", "green");
}
}
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.BadRequest, HttpStatusCode.BadRequest.ToString(), "If input value or/and format is invalid.", "red");
if (currentTokenRequiredAttribute != null && currentTokenRequiredAttribute.TokenRequired)
{
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.Unauthorized, HttpStatusCode.Unauthorized.ToString(), "If token is invalid or not given.", "orange");
}
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.Forbidden, HttpStatusCode.Forbidden.ToString(), "If action is forbidden.", "orange");
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.NotFound, HttpStatusCode.NotFound.ToString(), "If resource is not found.", "orange");
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.Conflict, HttpStatusCode.Conflict.ToString(), "If data conflicts.", "orange");
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.InternalServerError, HttpStatusCode.InternalServerError.ToString(), "If server feature is not working or has defect(s).", "red");
bodyBuilder.AppendFormat(httpStatusFormat, (int)HttpStatusCode.NotImplemented, HttpStatusCode.NotImplemented.ToString(), "If server feature is not implemented yet.", "red");
bodyBuilder.Append("</ul>");
#endregion Http Status
builder.AppendFormat(panel, one.Name, bodyBuilder.ToString(), one.Name, "#");
}
}
}
}
/// <summary>
/// Writes the API service HTML document panel.
/// </summary>
/// <param name="builder">The builder.</param>
/// <param name="apiServiceType">Type of the API service.</param>
/// <param name="apiContractOptions">The API router identifier.</param>
protected void WriteApiServiceHtmlDocumentPanel(StringBuilder builder, Type apiServiceType, IApiContractOptions apiContractOptions)
{
if (builder != null && apiServiceType != null && apiContractOptions != null)
{
HashSet <string> apiOperationHash = new HashSet <string>();
var bodyBuilder = new StringBuilder("<ul>");
var baseUrl = apiServiceType.FullName + ".html#";
var list = apiServiceType.GetMethodInfoWithinAttribute <ApiOperationAttribute>(true, BindingFlags.Instance | BindingFlags.Public).OrderBy <MethodInfo, string>((m) => m.Name);
foreach (var one in list)
{
var apiOperationAttribute = one.GetCustomAttribute <ApiOperationAttribute>(true);
var id = GetApiOperationIdentifier(apiOperationAttribute);
if (!apiOperationHash.Contains(id))
{
bodyBuilder.Append("<li>");
bodyBuilder.AppendFormat("<a href=\"{0}\" title=\"{1}\">{1}</a> <span style=\"font-weight: bold;font-style: italic;color: #666666;\">({2})</span>", baseUrl + one.Name, one.Name
, string.Format("{0}: /api/{1}/{2}/{3}", apiOperationAttribute.HttpMethod, apiContractOptions.Version, apiOperationAttribute.ResourceName, apiOperationAttribute.Action).TrimEnd('/') + "/");
bodyBuilder.Append("</li>");
apiOperationHash.Add(id);
}
}
bodyBuilder.Append("</ul>");
builder.AppendFormat(panel, string.Format("{0} ({1})", apiServiceType.Name, apiServiceType.Namespace), bodyBuilder.ToString(), apiServiceType.Name, apiServiceType.FullName);
}
}
