search

mozillascience / PaperBadger

Issuing badges to credit authors for their work on academic papers
https://badges.mozillascience.org/
Mozilla Public License 2.0
95 stars 45 forks source link

Some research on documentation frameworks for APIs #194

Open josmas opened 8 years ago

josmas commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

@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 commented 8 years ago

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

josmas commented 8 years ago

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!