Add support for documenting API

[Ugtan]

Although, the wiki here is enough to interact with the API but adding a support for API documentation will help people new to the repo, understand what the API can do without access to source code. It will also help them to see all the API endpoints available so that they can use these endpoints to test and analyze the requests and responses of the API endpoints which is not really possible in entering curl commands.

[Ugtan]

If it sounds good to you, i would like to add PR for the same. Thanks

[rtgdk]

Looks a good idea to me. Keep the module library as little as possible. Do not include unnecessary python modules for creating documentation and snippets. Use the DRF built-in docs api wherever possible.

[Ugtan]

I have actually tried using a third party module and not the build in docs api. I think it is better than the coreapi(as it supports swaggerui and redocs view as well). Please have a look and let me know if i should proceed with it or not. Also, if it doesn't work out we can switch to the default one.

[rtgdk]

@Ugtan You can try using this one. Still I would prefer using the default one provided by DRF, since a new third party module will add new maintenance checks. Go for the third party one and lets see if it is worth it.

[Ugtan]

@rtgdk I tried using the default one by it does have the option for file upload and we might have to change some source code which is not good. Although, i will make a PR of the mention one.

PS- Sorry about closing the issue, there was a pop up in my phone and i was closing it and by mistake closed the issue

[BassCoder2808]

Hi @rtgdk @Ugtan I would like to contribute to this issue if it is still open, it would be great if you could help me get started with it like how much work has been previously done and what more needs to be added to the documentation

[rtgdk]

@BassCoder2808 There has been some work done on this but wasn't merged. You can find the changes by @Ugtan on https://github.com/spdx/spdx-online-tools/pull/104 using drf_yasg but we faced some issues on hosting it as well as some apis doc not generated correctly.

Ideal solution would be to generate swagger specs directly from the api defined and host it directly on github.io

[BassCoder2808]

Hi @BanulaKumarage, as far as I had understood the issue because I was currently working on it :), we need to create the API documentation for all the current end-points in Swagger-ui. I had gone through your PR and @rtgdk can correct me if I am wrong, we need not change the API app urls.py because in the end it only consists of the backend server and a user would only POST the data there, instead we should change the SRC app urls.py because this documentation would be visible on the mail spdx tools site, as mentioned in the Add support for documenting API

[BanulaKumarage]

Hi @BanulaKumarage, as far as I had understood the issue because I was currently working on it :), we need to create the API documentation for all the current end-points in Swagger-ui. I had gone through your PR and @rtgdk can correct me if I am wrong, we need not change the API app urls.py because in the end it only consists of the backend server and a user would only POST the data there, instead we should change the SRC app urls.py because this documentation would be visible on the mail spdx tools site, as mentioned in the Add support for documenting API

Hi @BassCoder2808 when we add the url in url.py in API, we can access this endpoint of swagger endpoint through our application using api/swagger endpoint.

[BassCoder2808]

Hi @BassCoder2808 when we add the url in url.py in API, we can access this endpoint of swagger endpoint through our application using api/swagger endpoint.

Yes totally agreed we can put that in API app itself and it would work perfectly, but the previous work done on this as well as what I was doing was focused on the SRC app because the main goal is to host the documentation on github.io. That's where the main problem is occurring, you can see this Add support for API documentation for more detail, currently, I am also stuck at the same step for example documentation is being generated but how would we be able to host and change the same

[BanulaKumarage]

Hi @BassCoder2808 when we add the url in url.py in API, we can access this endpoint of swagger endpoint through our application using api/swagger endpoint.

Yes totally agreed we can put that in API app itself and it would work perfectly, but the previous work done on this as well as what I was doing was focused on the SRC app because the main goal is to host the documentation on github.io. That's where the main problem is occurring, you can see this Add support for API documentation for more detail, currently, I am also stuck at the same step for example documentation is being generated but how would we be able to host and change the same

@BassCoder2808 Need a clarification. The requirement is to have an API documentation. So why is it focusing specially on deploying it in github.io. But if its really needed, I have some idea to achieve that using this endpoint. I will try that and update the PR.

[rtgdk]

@BanulaKumarage @BassCoder2808 Ideally we only want to host api urls.py as that gives the user to interact with the application in a programmatical way. The application should ideally be updated to use those endpoints internally which is not currently there (as you can see some differences b/w app and api implementation).

Also, we want to host this documentation online. Currently it exists here - https://github.com/spdx/spdx-online-tools/wiki/REST-API-Fields-Request-and-Response and every fields in every api should be documented on the generated swagger page. We might have to update documentation inside django using https://github.com/spdx/spdx-online-tools/wiki/REST-API-Fields-Request-and-Response or even write/update new one. Idea is have an autogenerated way of adding new api along with documentation as keeping in wiki is tedious.