Radish is a simple .Net library that allows you to auto-generate HTML-documentation for your REST API on the basis of attributes in the source code. Radish is an acronym that means REST API Documentation In the Source to Html.
PM> Install-Package Radish
- you do not need to create REST API documentation manually;
- you do not need to sync your documentation file with changes in the code, as it needed for other popular generators, like Swagger or ApiBlueprint;
- unlike the ASP.NET Web API Help Page solution, Radish does not require WebHost, Mvc and Razor libraries, and suits for small self-hosting RESTful servers;
- all documentation is a single HTML-page with CSS and JavaScript embedded.
Writing documentation in the source code with Radish looks like:
// Documentation starts here
[Order("pets", 2)]
[Method("GET", "/api/pets/<id>", "pet-get-by-id")]
[MethodTitle("Get pet")]
[MethodDescription("Returns Pet object by specified id.")]
[RequestParameter("id", "Integer", "Id of the Pet")]
[ResponseBodyDescription("Json-serialized Pet object")]
[ResponseBodyExample(@"{""Id"":1, ""AnimalType"":""Cat"",""Name"":""Lisa"",""Breed"":""Turkish Angora"",""Age"":2,""Color"":""White""}")]
[ResponseCode(200, "OK. On successful result.")]
[ResponseCode(404, "Not Found. When pet with specified id was not found.")]
// Documentation ends here
[HttpGet]
[Route("pets/{petId:long}")]
[ResponseType(typeof(Pet))]
public IHttpActionResult GetPet(int petId)
{
Pet pet = DataBase.Instance.GetPet(petId);
if (pet == null)
{
return this.NotFound(String.Format("Pet with id = {0} not found.", petId));
}
return Ok(pet);
}Radish uses own simple template engine to create HTML documentation page, and you can freely customize its output. Let's take a look on the output documentation examples (example 1, example 2) for this simple demo. Also check the guide how to use Radish.
Radish is licensed under Apache 2.0 license.
Radish icon created by Creative Stall from Noun Project.