ValiDoc 0.7.0-beta

ValiDoc

An unobtrusive extension to FluentValidations for documenting validation rules.

Usage

1. Install ValiDoc via NuGet

Install-Package ValiDoc -Pre

2. Configure Dependency Injection

public void ConfigureServices(IServiceCollection services)
{
    // Add ValiDoc dependencies
    services.AddValiDoc();
}

3. Reference ValiDoc namespace

using ValiDoc;

4. Constructor Inject the RuleDescriptor

private readonly IRuleBuilder _ruleBuilder;

public ValidationController(IRuleBuilder ruleBuilder)
{
    _ruleBuilder = ruleBuilder;
}

4. Create an instance of DocBuilder that will be used to build the documentation

var docBuilder = new DocBuilder(_ruleBuilder);

5. Invoke the .Document() method on the DocBuilder, passing in an implementation of AbstractValidator<T>

var ruleDocumentation = docBuilder.Document(myValidatorInstance);

Example

Implementation of AbstractValidator<T>

public class MultipleRuleSingleChildValidator : AbstractValidator<Person>
{
	public MultipleRuleSingleChildValidator()
	{
	    RuleFor(p => p.FirstName).NotEmpty();
	    RuleFor(p => p.LastName).NotEmpty().MaximumLength(20);
        RuleFor(p => p.Address).SetValidator(new AddressValidator());
	}
}

Dependency Injection and Invocation

[Route("api/[controller]")]
public class ValidationController : Controller
{
    private readonly IRuleBuilder _ruleBuilder;

    public ValidationController(IRuleBuilder ruleBuilder)
    {
        _ruleBuilder = ruleBuilder;
    }

    [HttpGet]
    public IEnumerable<RuleDescriptor> ValidatorDocumentation()
    {
        var validator = new MultipleRuleSingleChildValidator();

        var docBuilder = new ValiDoc.DocBuilder(_ruleBuilder);

        return docBuilder.Document(validator);
    }
}

Output

[
    {
        "memberName": "First Name",
        "rules": [
            {
                "validatorName": "NotEmptyValidator",
                "failureSeverity": "Error",
                "onFailure": "Continue",
                "validationMessage": "'First Name' should not be empty."
            }
        ]
    },
    {
        "memberName": "Last Name",
        "rules": [
            {
                "validatorName": "NotEmptyValidator",
                "failureSeverity": "Error",
                "onFailure": "Continue",
                "validationMessage": "'Last Name' should not be empty."
            },
            {
                "validatorName": "MaximumLengthValidator",
                "failureSeverity": "Error",
                "onFailure": "Continue",
                "validationMessage": "'Last Name' must be less than {MaxLength} characters. You entered {TotalLength} characters."
            }
        ]
    },
    {
        "memberName": "Address",
        "rules": [
            {
                "validatorName": "AddressValidator",
                "failureSeverity": "Error",
                "onFailure": "Continue",
                "validationMessage": "N/A - Refer to specific AddressValidator documentation"
            }
        ]
    }
]

Supported Scenarios

1. Extraction of validation messages (Configured argument values not included)
2. Built in validators
3. Chained validators for the same property
4. Complex properties
5. Cascade behaviour

Future Roadmap

1. Collections
2. RuleSets
3. .WithMessage()
4. .WithName()
5. Validation arguments (Greater than 10 characters for example)
6. Custom validators
7. .Must()