Sebiworld
Swagger documentation
It would be really useful to have automatic Swagger documentation for our API.
Hi @spoetnik !
That sounds interesting! Let's work together! How exactly do you envision that? Are you already familiar with Swagger?
Let me get a few thoughts out of my head:
- For the default endpoints, i.e. the /auth functions, I could of course write Swagger documentation and provide it in the module.
- All self-defined endpoints can be found either in Routes.php, or in modules that register an endpoint via hook.
- Because of the hook-registration, we could actually only generate such a documentation at runtime, e.g. as a subpage in the ProcessWire backend under setup/AppApi...
- There we would have the info about all endpoints, but no descriptions yet. Where would you put the other information?
Sounds amazing, could probably use the phpdoc syntaxis, it even allows Markdown as part of the description and can be accessed via php https://www.php.net/manual/en/reflectionclass.getdoccomment.php https://stackoverflow.com/questions/11741302/how-do-i-put-blocks-of-php-code-into-a-phpdoc-docblock
happy to help with this if needed
With v1.3.0 I have implemented a solution for this which does not need to read the php files and their phpdoc comments like @laikmosh said. I hope that this solution does fit in your workflows as well. My project apis have become much clearer since the update and I can very easily import the Swagger documentation that is generated into Postman for testing! Have a look at the wiki-page to see how it is done.