Swagger documentation

[spoetnik]

It would be really useful to have automatic Swagger documentation for our API.

[Sebiworld]

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?

[laikmosh]

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

[Sebiworld]

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.