Plots2: Documentation of token system for write API

Hey @jywarren can i work on it?

For sure, thank you!

Sorry for not documenting the feature at that point in time as I was in a haste to complete the tasks on the timeline. Thanks for volunteering to work on it, @namangupta01! I would love to review it once you finish documenting.

No problem at all! Teamwork!

@ryzokuken Thank you! :)

@jywarren @ryzokuken So i was working on this issue, i was wondering that do i only have to document about comments through token i.e https://github.com/publiclab/plots2/pull/1513/files ?

@namangupta01 correct! This is the PR where I actually wrote the code for commenting through a token.

Hi, everyone! Can I help with this too? How is it going so far? I was thinking about start writing the token documentation to familiarize more with the API.

@stefannibrasil I think this is abandoned for now, so you may feel free to go ahead and work on this. Let us know if you face any issues.

Thanks, @ryzokuken I am gonna start working on documenting the token feature this week. I am going to see some examples and I'll let you know anything, of course. Thanks for the help!

@sukhbir-singh do you wanna start working on this too? We can compare our work later.

Yeah! sure :smile:
@stefannibrasil you active on gitter??

HI @jywarren and @ryzokuken! After reading more the docs provided here, I have some questions to ask:

• The files in app/api/src/ folder are the docs that Swagger uses to generate the Interface, right?

• In order to generate the documentation for the token authentication, do I need to create a new file in the folder mentioned above, showing how the CommentController create action works?

That's what I understand so far. I would appreciate if you could give a little more information on that. Thanks!

@stefannibrasil for saving time and effort, I had avoided making the "commenting over tokens" action a part of the existing Swagger API spec, and had made a standalone function in the Rails codebase (in CommentController, you're right) and made a route for that.

I don't think Swagger allows you to document external functions, but I might be wrong.
So, I believe you should just add some documentation by yourself in doc/api.md in markdown format, explaining a little how the function works and how we expect users to add their own comments using this endpoint.

I hope that makes it clear, feel free to ask for clarification on any of this.

That makes sense, thanks! After looking more at the docs and how to write API docs, I added some changes to this PR. I am not sure if that's the type of documentation you were asking for.

I added my questions in the description, could you please take a look and see if you can help me?

I couldn't find much documentation about the token, you can tell me where to look more too, that would help! :)

@sukhbir-singh sorry, I am not on gitter, but if you want, you can contribute in the PR too, that would be great.

@stefannibrasil you can check out this video for demo showing how to use postman for making request on comment API. :balloon:

Great, is this complete, or is there more we could break out about this one? Feel free to close it up if it's done! Thanks, all!!!

Actually perhaps we can add a couple additions -- like, could we refine POST https://publiclab.org/comment/create/token/id.:format to POST https://publiclab.org/comment/create/token/id.json to show you can specify the format like that. And maybe we should link to where the token API code is in the source?

https://github.com/publiclab/plots2/blob/master/app/controllers/comment_controller.rb#L48-L73

@jywarren +1, that sounds perfect.

Hey, everyone! These are good points, thanks! The PR was already merged, I'll add this and create another one then =)

Also, thanks @sukhbir-singh thanks for all the help here!

No problem...!! Happy to help. I am very active on github, gitter and irc, you can ping me there further if you need help in any case. :smiley: