Auto Generate Documentation for ASP.net WebAPI

Question

I currently have a MVC project in ASP.Net that is using a WebApi. Most of the code for the controllers is written in c#. I'd like to automatically generate a description of API calls including:

1.) The url of the page/endpoint

2.) Description of what endpoint/page does

3.) List of arguments with descriptions and datatypes.

4.) HTTP Verb (get, post, put, delete)

5.) The permissions required for the page

The description will have to be written manually.

I've read quite a few other articles that result in the individual using a 3rd party application like Swagger. Is there something built in to ASP.Net to help with this? If I wanted to try to generate documentation myself (without using 3rd party software), how would I get started on creating such documentation?

I've spent a fair amount of time googling various queries and can't seem to find an answer.

Edit: What's the benefit of using Swagger over ASP.Net help pages in my case?

Something like this? asp.net/web-api/overview/getting-started-with-aspnet-web-api/… — David
– David, Commented Jun 12, 2015 at 14:40
That looks like it could be what I was looking for. I'll take a look at it, then get back. Thanks for the quick reply. — Speerian
– Speerian, Commented Jun 12, 2015 at 14:42
Swagger is even used by Azure API Apps, so you should probably prefer it. You can use Swashbuckle to generate the documentation — Panagiotis Kanavos
– Panagiotis Kanavos, Commented Jun 12, 2015 at 14:49
@PanagiotisKanavos What's the benefit of using Swagger over ASP.Net in my case? — Speerian
– Speerian, Commented Jun 12, 2015 at 15:46
If your swagger api consumer is something like SwaggerUI, it would allow users to try out the api calls right from the documentation — John
– John, Commented Jun 12, 2015 at 15:50

Jamie Keeling · Accepted Answer · 2015-06-13 11:01:40Z

21

As an alternative to Swagger you can make use of the 'Help Pages' for ASP.NET Web API.

Entries within this documentation are generated automatically and will contain information such as:

Relative URI
HTTP Method
Sample Request/Response data
A description of the API purpose (derived from XML comments)

If using a third party component is possible then I would recommend you use Swagger (Use the Swashbuckle NuGet package) to achieve API documentation.

edited Jun 13, 2015 at 11:01

answered Jun 12, 2015 at 14:42

Jamie Keeling

9,99617 gold badges68 silver badges105 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Phil Over a year ago

The downside of using Help Pages is that it adds a ton of stuff to your project. The downside of Swagger/Swashbuckle is that it doesn't support multiple Web API actions at the same URL path but with different parameters.

Nick · Accepted Answer · 2015-06-12 16:20:20Z

5

Swagger does not just list your api uris. Users actually try them out and see the response

Swagger has tools to create the documentation before you implement it.

It can also add description using the comments.

answered Jun 12, 2015 at 16:20

Nick

3,3776 gold badges32 silver badges42 bronze badges

Collectives™ on Stack Overflow

Auto Generate Documentation for ASP.net WebAPI

2 Answers 2

1 Comment

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Related