Webinar: Documenting RESTful APIs

Speaker: Andy Wilkinson
An API's documentation is a vital part of making it easy to understand and easy to use. RESTful APIs are no different. In this webinar we'll look at what should be included in your RESTful API's documentation and, just as importantly, what should be omitted. To illustrate this we'll look at some real-world examples of good and bad API documentation.

We'll look at some of the problems and limitations of choosing a tool like Swagger to produce your API's documentation and conclude by looking at some alternatives that are better-suited to producing documentation that your users will love.

[windmaomao]

I'm not so sure why we have to start with what the tool can not do. Especially the tool is trying to do things that nobody else did.

Idea starts small.

[aviramvijh]

Thanks a lot for this helpful presentation.

[tomdemeranville]

While I like the test driven approach and the framework you're promoting and also agree with much of your talk, a lot of your argument against swagger assumes that people using Swagger use it exclusively and write nothing else.  That is far from realistic.  If you put the effort into writing decent documentation (as you recommend and your tool requires) then swagger supplements the written documentation rather than replaces it.