How is the Stack Exchange API documentation generated?

Question

I was just going through the pile of SE websites and just found Stack Exchange API. The documentation for each REST endpoint or URL is given in detail. Also, the API methods are listed and a separate page is given to describe each REST endpoint.

1. API Methods:

   

2. Individual Method Description:

   

Stack Exchange is built using C#, ASP.NET MVC evident from this answer., and many other technologies. What language is the Stack Exchange API written in?

If it is written in C#, then what tools are used for documentation? How is the documentation created?Are they using only XML comments or some library?

Answer 1

The Stack Exchange API is a .NET MVC4 app written in C# 4 (technically 5 now, but it isn't using any async/await stuff).

The index page is just a view, maintained more or less by hand.

For methods there's nothing magic there, it's just a collection of views with a common master. A similar approach is taken for types.

Here's (most of) the view for /answers

@{
    Layout = "~/Views/Documentation/Method.cshtml";
}

@section MethodName { /answers }

@section Discussion
{
<p>Returns all the undeleted answers in the system.</p>

<p>The sorts accepted by this method operate on the follow fields of the <a href="/docs/types/answer">answer object</a>:
    <ul>
        <li><strong>activity</strong> &ndash; <code>last_activity_date</code></li>
        <li><strong>creation</strong> &ndash; <code>creation_date</code></li>
        <li><strong>votes</strong> &ndash; <code>score</code></li>
    </ul>

    @(DocsTypeDescriber.DefaultSort<AnswerSort>())<br>
    <br>

    It is possible to <a href="/docs/min-max">create moderately complex queries</a> using <code>sort</code>, <code>min</code>, <code>max</code>, <code>fromdate</code>, and <code>todate</code>.
</p>
}

@section Type
{
    <p>This method returns a list of <a href="/docs/types/answer">answers</a>.</p>
}

@section ConsoleParameters
{
    @{
        var param = ApiParameters.DescribeWithSort<AnswerSort>();
        var filterName = ApiFilter.Default.EncodeFilter();
        var filter = ApiFilter.Default.Describe("2.1");
        var dependentTypes = StackOverflow.Api.V2.Helpers.FilterableAttribute.GetDependentFilterableTypes(typeof(Answer)).Keys.Union(new[] { typeof(ApiResult<>) }).Select(s => s.GetApiName()).ToList();
    }
    <script type="text/javascript">
        var parameters = @param.ToJSON();
        var method = "/2.1/answers";
        var filterName = "@filterName";
        var filter = @filter.ToJSON();
        var dependentTypes = @dependentTypes.ToJSON();
    </script>
}

Our API is very regular, so all the documentation views look very similar.

This system is "new" (I guess years old now) to v2.0. In v1.0 we did try some automatic documentation generation using in source comments but it turned into a maintenance nightmare, and was kind of difficult to make work with more interesting methods.