search

veritus / veritus-backend

1 stars 0 forks source link

Document API #53

Closed Ragnar-H closed 6 years ago

Ragnar-H commented 7 years ago

Spawned from discussion in #20

Description

With an ever growing API interface, it will be a great benefit if developers can get a quick overview of what the API is capable of.

Thoughts

In my mind a successful documentation gives quick access to example input/output, allows devs to make HTTP calls, is autogenerated (or at the very least, lives in the code).

My reasoning behind the need for autogeneration, is that writing documentation takes time, and is very often overlooked when developing, and quite often out of date. Misinformation is worse than no information.

Todos

Ragnar-H commented 7 years ago

@skabbi I've outlined how I'd like to see this issue resolved.

But this is very biased. I think you should take ownership of this and run with it.

AriHrannar commented 7 years ago

Autogenerated is a must I think. Its tedious to keep it up manually and something always gets forgotten.

skabbi commented 7 years ago

Autogenerated it will be then. @AriHrannar could you send me your Postman collection to help me test the API doc that will be created.

AriHrannar commented 7 years ago

Apiary might be something cool to look into. Maybe Google-ing around will give some good hits as well :)

I did share postman and this was the result. Its probably not everything and I am not even sure everything is correct :) its been such a long time since I did any webservice stuff in the backend :(

skabbi commented 6 years ago

Investigate available tools I looked over Apiary and although it would probably fit our needs, for now, it has payment plans. I also looked over the official Django REST documentation page and decided on Django REST Swagger. Mainly because I had heard good things of Swagger and it looked the prettiest. I feel that other tools will be at best as good as Swagger, so not worth spending too much time on them.

Outline short summary of these tools with, pros | cons, pricing, what needs to be done by dev team Apiary:

Django REST Swagger:

Outline how developers should keep documentation up to date Using the minimal setup for autogeneration, as described here, gives us a lot with no work.

Document existing endpoints By only adding a few lines of code to urls.py, it seems like every endpoint is now documented and testable via Swagger by opening http://localhost:8000 in the browser.

@AriHrannar @Ragnar-H I've created the branch infrastructure/document-api, but I don't seem to have permission to push code to the repo. Also, how do I move issues to "In Progress"?

Ragnar-H commented 6 years ago

Awesome work 🙌

I suppose the only thing we need to keep up to date are the docstrings mentioned in the article

I've created the branch infrastructure/document-api, but I don't seem to have permission to push code to the repo

My bad, that should be fixed

Also, how do I move issues to "In Progress"?

You can use the "Pipeline" in the top corner of issues (see screenshot). But I get a kick out of dragging the tickets around in the Zenhub "Board" view 😊

screen shot 2017-07-28 at 10 24 47

Looking forward to see your work 🎊

AriHrannar commented 6 years ago

@skabbi I would recommend installing zenhub for Chrome (should be available for Firefox and Opera as well if that is what you are into). Then you will get some additional tabs in the repo (like board) :)

Awesome job as well!

skabbi commented 6 years ago

@Ragnar-H I'm still unable to push code, can you double check it has been fixed?

@AriHrannar I have ZenHub installed, but it seems I don't have permission to change the status of an issue.

skabbi commented 6 years ago

Created pull request.

@AriHrannar @Ragnar-H Please look over it and tell me your thoughts. I also added, hopefully accurate, docstrings to make the endpoints more descriptive.

skabbi commented 6 years ago

Pull request merged. Closing issue.

Ragnar-H commented 6 years ago

\o/