search

veritus / veritus-backend

1 stars 0 forks source link

Add link to Postman collection to README #20

Closed AriHrannar closed 6 years ago

AriHrannar commented 7 years ago

@Ragnar-Hardarson commented on Wed Mar 01 2017

Postman allows for sharing collections of calls. @AriHrannar could you please share your collection? image

skabbi commented 7 years ago

What is the status of this issue? Also, wouldn't it be a good idea to document the API somewhere?

AriHrannar commented 7 years ago

Yes definitively!

Im thinking this will most likely fall on my shoulders as I wrote most of the API.

@skabbi @Ragnar-H

Any suggestions on how you guys have seen API documentation done?

At my work we use the Github Wiki for example

My suggestion would be

  1. Create a repository for all postman API calls (I can do this)
  2. Add pages for all API endpoints in the Github wiki

Anything else?

Ragnar-H commented 7 years ago

We're using swagger at my workplace. It automates the documentation, which is the only way to go in my opinion. Keeping Github pages up to date gets very tedious. If there is no tool that does this automatically, then I say we do not document the endpoints. I'd much rather work on an undocumented API than one with out of date documents.

I also believe the Django-rest admin view is good enough for this

Ragnar-H commented 7 years ago

But I do want to get my hands on your postman collection ☺️

Which should be a part of a PR? thinking out loud

AriHrannar commented 7 years ago

True about the django-rest admin site. Forgot about that.

I have heard about swagger, maybe create an issue for setting that up if its useful? Have not looked into it at all.

Ragnar-H commented 7 years ago

Swagger

I don't feel like it gives us anything more than the Django-admin site.

skabbi commented 7 years ago

I think creating some API docs would be a good place for me to start contributing a bit, with some help from you. So please let me know what tool you would like to be used and preferably a link to some documentation for it.

Ragnar-H commented 7 years ago

Well I was wrong about Swagger. Marc Gibbons has made a package specifically for django-rest http://www.django-rest-framework.org/topics/documenting-your-api/#django-rest-swagger

The "django-rest admin site" is also mentioned on that site.

I'll make an issue with this an assign @skabbi

AriHrannar commented 7 years ago

@Ragnar-H @skabbi thoughts on closing because of Swagger? Dont see this providing us with any more value

skabbi commented 7 years ago

Good question. It would be nice to have default collection that can be used, but probably not worth the hassle of maintaining it since we have Swagger.

I think it can be closed.

Ragnar-H commented 6 years ago

Closed since Swagger serves the same purpose