Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for documenting API #91

Open
Ugtan opened this issue Mar 8, 2019 · 12 comments
Open

Add support for documenting API #91

Ugtan opened this issue Mar 8, 2019 · 12 comments
Labels

Comments

@Ugtan
Copy link
Collaborator

Ugtan commented Mar 8, 2019

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
Copy link
Collaborator Author

Ugtan commented Mar 8, 2019

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

@rtgdk
Copy link
Collaborator

rtgdk commented Mar 11, 2019

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
Copy link
Collaborator Author

Ugtan commented Mar 11, 2019

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
Copy link
Collaborator

rtgdk commented Mar 21, 2019

@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
Copy link
Collaborator Author

Ugtan commented Mar 21, 2019

@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
Copy link
Contributor

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
Copy link
Collaborator

rtgdk commented Mar 12, 2023

@BassCoder2808 There has been some work done on this but wasn't merged.
You can find the changes by @Ugtan on #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
Copy link
Contributor

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
Copy link
Contributor

BanulaKumarage commented Mar 25, 2023

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
Copy link
Contributor

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
Copy link
Contributor

BanulaKumarage commented Mar 25, 2023

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
Copy link
Collaborator

rtgdk commented Mar 26, 2023

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants