WebAPI - автоматически генерировать документацию со всеми возможными ответами

Question

Я прочитал статью http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages и она отлично работает. Но я бы предпочел добавить все возможные ответы и условия, когда эти ответы будут отправлены. Любой инструмент для анализа каждого метода WebAPI, найти все места с ответами, почему это может произойти и автоматически создать документацию о нем?

Т.е. у меня есть следующий код:

    public HttpResponseMessage GetEditorialRequests()
    {
        SetUser();
        try
        {
            var r_list = _service.RequestList(user.Id);
            if (r_list.Count > 0)
            {
                var list = mapper.Map<List<SmartphonePhotographerRequestElementApiModel>>(r_list);
                return Request.CreateResponse<List<SmartphonePhotographerRequestElementApiModel>>(HttpStatusCode.OK, list);
            }
            else
                return Request.CreateResponse(HttpStatusCode.NoContent);
        }
        catch (PixlocateBusinessLogic.NoSmartphonePhotographerLocationException)
        {
            return Request.CreateErrorResponse(HttpStatusCode.BadRequest, new HttpError("User does not have any locations") { { "CustomStatusCode", 466 } }); 
        }
    }

Я хотел бы иметь документацию, которая описывает этот метод возвращает:

1. StatusCode = 200 и список элементов, когда метод успешно завершен и элементы найдены
2. StatusCode = 204, когда метод успешно завершен и элементы не найдены
3. StatusCode = 400, когда местоположение не найдено (условие для получения редакционных запросов) и подробный ответ с сообщением и CustomStatusCode

Answer 1

Вы пробовали Swagger (и Swashbuckle)?

развязность

Swagger - это простое, но мощное представление вашего RESTful API. Благодаря самой большой в мире экосистеме инструментов API тысячи разработчиков поддерживают Swagger практически во всех современных языках программирования и средах развертывания. Благодаря API с поддержкой Swagger вы получаете интерактивную документацию, создание клиентского SDK и возможность обнаружения.

Swashbuckle

Легко добавляет Swagger в проекты WebApi! Комбинирует ApiExplorer и Swagger/swagger-ui, чтобы предоставить своим пользователям API богатый опыт поиска, документации и игровых площадок. В дополнение к генератору Swagger Swashbuckle также содержит встроенную версию swagger-ui, которая будет автоматически отображаться после установки Swashbuckle. Это означает, что вы можете дополнить свой API удобным интерфейсом обнаружения, чтобы помочь потребителям в их усилиях по интеграции. Более того, он требует минимального кодирования и обслуживания, что позволяет вам сосредоточиться на создании потрясающего API!

Я использую их во многих проектах, очень простой в использовании и чрезвычайно мощный.