Enterprise Web API Documentation
Revelio gives you plenty of functionality out-of-the-box through the intuitive engine and standard attributes, but every API is unique. Therefore, Revelio supports custom information discovery in the form of attributes and processors. To start, you'll want to install the Revelio.Extend NuGet package in your .NET Web API project.
PM> Install-Package Revelio.Extend
Revelio has four interfaces that support customizable documentation:
For example, a site may use an attribute RequirePermission on individual endpoints. This attribute takes one or more permission names, which can be highlighted in Revelio.
Custom information is added via the Metadata dictionary, which is then displayed via a custom view.
Processors are similar to attributes in that they allow you to modify information or add new metadata to your documentation. However, processors are different in that they are run on every respective object, as opposed to attributes that are only run on the objects they decorate.
For example, say the RequirePermissionAttribute class described earlier was an external class, so we couldn't modify the code to add the IEndpointDocumentationAttribute implementation. Instead, we can write a processor that adds the metadata for any endpoint with that attribute.
The final step is to add this processor to the project's Revelio configuration. This is a class that implements IRevelioConfiguration declared in the Web API project. Revelio will use this class to add custom processors.
Now this processor will be run every time the documentation is generated. In order to simplify your development,
Revelio will ignore any
NotImplementedException thrown from this class.
Many times you'll find yourself writing a processor to search for a specific attribute. Revelio provides the helper processor
FindAttributeProcessor<T> for such a case.
We could rewrite the RequirePermissionsProcessor to the following: