Some research on documentation frameworks for APIs

[josmas]

Something like swagger but it does not have to be Swagger. Currently the API endpoints are being documented in the main page and the Readme, but as the API grows, that solution will start to fall short.

[Alicole]

@josmas -- is there any way of automating this approach, using some tools or scripts, or would we have to complete such documentation manually for every part of the API?

[josmas]

Hi @Alicole
Swagger has a number of tools like the editor and the codegen, but I have not used them. The more that can be done with a tool, the better! I am sure there are other options, but haven't really looked at (or used) any so far.

[geeeeeeeeek]

I think Swagger is a good solution. I used it in another open source project. The API endpoints are stored in a yaml file, so I'm afraid we have to manually do that for each of them. You can refer to https://github.com/gitlab-classroom/classroom-server/blob/master/api/swagger/swagger.yaml#L62.

And one thing that's good about using Swagger is that you can test and debug your endpoints very easily on a web page provided by Swagger UI. That's awesome.

[geeeeeeeeek]

@josmas If you need any help, feel free to find me. Using Swagger was one of my proposals that I gave to @acabunoc. But sorry I did not have much time to do it. If you like this solution, I would like to suggest refactoring the code with ES 6 together. You are gonna change a lot of code anyway...

[josmas]

Hey @geeeeeeeeek yeah, moving to ES6 is also something needed. It would be nice to split issues though; it's a lot easier to review smaller changes.

Some work to move to ES6 already done in #204 but it's difficult to separate it from the React upgrade, and the changes for the react code are not complete (WIP), so makes things harder to review and merge.

Any help much appreciated!

[geeeeeeeeek]

@josmas Yep it's always a good practice to split issues. BUT, if you are gonna move to ES 6, I'm afraid every single line would be changed and not merge-able with other branches. Why not everybody take some days off and do the dirty work in pipeline, instead parallel?

[josmas]

@geeeeeeeeek that's a great idea. Would you volunteer to do that? I personally need to catch up with other projects and not likely to come back to Paper Badger for a week or so. The #mozsprint is also over now, so the repo will likely be quiet for a while. Sync with @acabunoc if you plan to do so. Thanks!

[geeeeeeeeek]

@josmas Do you have any sprint for PaperBadger? I happen to be available for the next week, and busy for the following two weeks...

[josmas]

hey @geeeeeeeeek the sprint run for the last two days, so I guess things will be quiet this coming week.

[josmas]

Hey @geeeeeeeeek just checking if you've had any time to look into this; no worries either way. I've a bunch of other things I need to take care before this, so let me know if you are still interested. We may split the UI into an express app and a module for others to use some of our endpoints (with auth), so a bit of thought needs to be done here. Thanks!