[docs] Proper API specs/docs using Swagger

[eshaan7]

• Writing proper documentation for the API endpoint functions (api_app/api.py)

Need to use proper syntax as given here. Originally posted by @Eshaan7 in https://github.com/intelowlproject/IntelOwl/pull/344#issuecomment-786725761

• Using https://www.django-rest-framework.org/topics/documenting-your-api/ to generate docs and API specs
• Use this to create the spec file, and then use the sphinx-redoc extension to generate redoc along with rest of the docs. Then link both docs together with something like this. There should be a GH workflow setup for this.

[spiderxm]

assign me this issue

[purhan]

It's been a while since this was assigned to someone. I'd like to work on this if it's open for contribution!

[mlodic]

hey @Purhan thank you for your interest in the project! You have been assigned

[purhan]

@mlodic Thanks for assigning! I have created a PR. Review will be appreciated.

[CITIZENDOT]

Also I think we should rewrite the docstrings of the APIs because swagger cannot parse that data correctly.

Yes, it's our mistake for not following a proper syntax while writing doc strings.

Need to use proper syntax as given here.

descriptions for Operations, Parameters and Schemas are picked up from docstrings and help_text attributes in the same manner as the default DRF SchemaGenerator

Originally posted by @Eshaan7 in https://github.com/intelowlproject/IntelOwl/issues/344#issuecomment-786725761

So, Before diving into swagger, We have to fix doc strings, Right? Let me do that then.

[mlodic]

solved with #417

[eshaan7]

The GH action automation part of this issue still needs to be done. (could use https://github.com/NiklasRosenstein/readthedocs-custom-steps/)

[uzaxirr]

Hey, can anyone clarify what part of this issue is solved and what needs to be implemented more?

[fear-the-reaper]

Hello! Is this issue still open? If so can you clarify what needs to be done? Thanks!

[mlodic]

Honestly I did not understand what @eshaan7 meant by that. I guess this could be closed

[eshaan7]

The schema.yml file is not automatically updated and we need a GitHub action to manage this. (As you can see even right now, the schema.yml file says the version is 3.1.0 even though we are on 3.3.0)

This workflow could be made part of the existing sphinx_build_on_release.yml file.

The schema.yml file is generated using the drf-spectacular django app using the following management command:

$ python manage.py spectacular --file docs/source/schema.yml

[mlodic]

Yeah plus I honestly don't like the result we had with Redoc and would preferably move to Swagger.

[mlodic]

superseded by #2043