We have moved our forum to GitHub Discussions. For questions about Phalcon v3/v4/v5 you can visit here and for Phalcon v6 here.
  1. Home
  2. Beginners

How do you document restful apis? Automatic preferable.

Hello!

I'm building restful (trying..) api for application with micro from phalcon. And it have many incoming points with relations.

What best practicies to automatically write documentation/reference to that api?

For what:

  • Automatic generating html/markdown/some other visuals for other developers
  • Automatic updates to docs/refs when code is changed
  • Automatic testing/asserting responses from development version of api

Maybe, already exists tool for autograb from MicroCollections/MicroApp or something similar?

ps: sorry for my poor english ):



98.9k

Maybe integrate Swagger could do that work for you: https://github.com/zircote/swagger-php



21.7k
in reply to Phalcon

Maybe integrate Swagger could do that work for you: https://github.com/zircote/swagger-php

Thank you, seems useful, i'll try it!



104

@Roman any news on that topic?



21.7k
in reply to Martin F

Not really. Trying to use https://apidocjs.com but can't get this work with OAuth2 (maybe, it needs too much time for me) and ended up with write old good markdown docs by hand with just parsing PHPDocs from my controllers.

@Roman any news on that topic?



104

sad to here.... i am really looking for a nelmioapi like live api solution.



21.7k
in reply to Martin F
edited Jul '16

Thank you for package, i'll try it in next project!

In my company, i have fulltime frontend developer and we make this workflow:

  1. I automatically get routes and parameters for public APIs:

    1. Routes i get from configuration yaml file – it's easy.
    2. Parameters parsed from DockBlocks in controllers methods – easy too.
    3. CLI-script get info from 1.1 plus 1.2 and generates simple markdown file.
  2. Add manually descriptions for public users of my API (mostly not needed this step at all – because of DockBlocks).
  3. My frontend colleague write script that generate styled HTML from markdown. Here is The Magic!

So yeah, we have reinvented the weel but.. it takes much less time that implement already working solutions from this topic and from StackOwerflow-searched.

sad to here.... i am really looking for a nelmioapi like live api solution.



152

So just integrated swagger, if anyone needs inspirations you can have a look https://packagist.org/packages/igsem/phalcon-swagger