Add documentation

[gigili]

It would be nice if we had bot API endpoints and source code documented, but help with either one or both is more than appreciated.

For documenting PHP code we're using phpDocumentor and for the API endpoint documentation we will use Swagger-PHP and for more code samples and reference you can also check out another project which uses the same library for generating swagger-ui docs.

If you open any of the modules in the other project, and check any of the controller files, you will see the syntax and the code used to generate swagger documentation.

Any help and/or feedback is welcomed :)

[AnujaChangede]

Hi! If you are looking to add API Reference documentation to your project, I can help. If you can mention the tasks and point to markdown files, it would be helpful.

[gigili]

Hi, thank you for taking an interest in the project. Could you expand on what you mean by

Mention task

And

Point to markdown files

This project has no documentation at this point, but I did link a sample from another project which uses the mentioned technologies in the description above

[AnujaChangede]

Hi, thank you for taking an interest in the project. Could you expand on what you mean by

Mention task

And

Point to markdown files

This project has no documentation at this point, but I did link a sample from another project which uses the mentioned technologies in the description above

Hi @gigili, Thanks for your reply. I have checked the links given by you. I have used swagger; but I am relatively new. I have worked on API documentation where the files and setup was ready; not done anything from scratch. Do you have any pointers on how to get started? Thanks in advance.

[gigili]

So for the basic setup and starting from scratch it would be needed to install the swagger-php as a dev dependency for the project by running composer require zircote/swagger-php --dev .

Than in the index.php would be a general setup of the API docs using the PHP's doc block comments (sample can be found here ).

Than for each controller in the controllers folder and for each method within those controllers would the documentation need to be written ( example here ) again in the dock block comments.

If you're not familiar with swagger-php package (it takes a little bit of getting used to it) and would feel more comfortable with witting it all in just a swagger.json and I will convert it into comments later on, but would be helpful to have any kind of documentation available for the project or even just documenting code following the phpDocumentor guide on how to write code documentation if you have experience working with php.

[AnujaChangede]

phpDocumentor

Hi @gigili, Thank you so much for the detailed response. I have tried to install composer, however it requires PHP to be installed first. I could do that as well. Its just that I am not familiar with PHP. In the past, I have worked as a developer for C, C++ extensively and Java to a certain extent. So I do understand code. Currently I am working in API Documentation. I am keen on helping here (and learn in the process). If you think I can be of help, please let me know. Here are the steps I think I need to do -

1. Install PHP
2. Install composer
3. Check the controllers folder in the repo. I see there are 4 files there.
4. I checked one of the files - ListItemController.php. I see there are below listed public functions - get_list_items add_new_list_item update_list_item delete_list_item update_list_item_bought_state delete_list_item_image

What I understand is, I need to understand the code written for each of these functions and add code annotations that would help to generate the OpenAPI spec.

Is that correct? I can attempt that if thats what is required. Please let me know.

Thank you for your time.

[gigili]

Yes those steps seems correct, if you plan on running the project (using something like postman to test api endpoints) you will need to install docker as well, if you'll just write the docs there is no need for it.

I'm not sure what your OS is, but if you're using Windows I'd recommend going with xampp for your php setup.

Just a quick note that this project does require php 8 to be run or the composer won't let you add the new package.

If you need any more help, do ask and I'll try my best to help you out.