RESTful APIs Course 3: Documentation

We'll email you with updates

This course is in the planning stages

This course is still being planned. Writing documentation for your API is hard, and I'm still playing with ways that can read from our code but also give us enough flexibility. So far, I'm not happy. But if you're using Symfony2, check out the NelmioApiDocBundle. And stay tuned for updates :).

In Course 1, we learned the fundamentals. In Course 2 we took it a step further with linking, HATEOAS and pagination.

In our last installment, we're talking about API documentation. Huh? Yep, unlike a traditional website, if your API docs have missing or out-of-date details, your API is just plain un-usable.

In this tutorial, we'll experiment with an approach to creating a great API doc that's actually reads information from your code and updates dynamically. This is an area of growth: there are a lot of products and libraries to help. But there are also a lot of pieces missing - like how could I actually read my route information dynamically and use that in my API docs?

Release is not yet scheduled - if you're eager to see this, let us know!

Your Guides

William Durand Ryan Weaver Leanna Pelham

Questions? Conversation?

  • 2017-07-06 weaverryan

    No news - as I'm still not really satisfied with any solution. Well, that's not totally true :).

    1) If you're using Symfony, then NelmioApiDocBundle (as I mentioned earlier) is still great.
    2) I'd also recommend looking into ApiPlatform: This doesn't exactly give you documentation, it's a platform for building API's that includes a really nice, swagger-like documentation interface.

    I hope that helps!

  • 2017-07-04 SÅ‚awek Grochowski

    any news? What tools are using right now? Swagger? Nelmio? Or something else?

  • 2017-02-07 Raphael Schubert

    Cheers!!!! Awesome!

  • 2016-09-21 weaverryan

    Hey Alberto!

    This is still on our radar, but not on the current schedule - so I can't guarantee it'll happen in the next several months! However, you're definitely in good shape with NelmioApiDocBundle. There is some conversation - - about its future, but it's all still being decided. Until then, I highly recommend going with Nelmio :).


  • 2016-09-19 Alberto Castro

    Ryan, to your comment

    > Not on this one - I think we may skip this and cover it in an extra part of our Symfony REST series using NelmioApiDocBundle, which is very very nice to use :).

    I have to say that it seems like a very good idea since I am very interested in the NelmioApiDocBundle. Let us know when you are ready, looking forward to this important piece of the REST API development. Thank you.

  • 2016-05-19 weaverryan

    Not on this one - I think we may skip this and cover it in an extra part of our Symfony REST series using NelmioApiDocBundle, which is very very nice to use :).

  • 2016-05-19 Sergio Costa

    Hello Guys, do you have ETA for te launch ?

  • 2015-10-12 weaverryan

    No news on this one, as we haven't found a solution we like yet. But we *will* talk about documentation in the Symfony REST series using the awesome NelmioApiDocBundle.


  • 2015-10-11 Marius Puiu

    Any news on this episode?

  • 2015-08-19 SPIRITED

    Somebody please comment so that I can get a notification when this topic is publishe

  • 2015-06-08 Ahmmad Ismail

    I am eager to see this

  • 2015-03-23 weaverryan

    Definitely on a Symfony2 project... but if you're not using the framework (even Silex), there's no homerun tool :(.

  • 2015-03-21 Almog Baku

    nelmio api doc?

  • 2015-03-04 Sergio

    Hello Guys! I am looking forward for this episode! =) Tks

  • 2015-02-25 weaverryan

    You're right - thanks for pointing that out. I've removed the release date for now - this one has stalled because I haven't been satisfied with the solutions yet. It highlights how tricky this stuff is (obviously writing docs is not too hard, but making something that pulls from your code base - to avoid duplication - is a bit trickier). I'll re-add a release date when I have it!


  • 2015-02-25 urosg

    It's almost end of February.