search

hebcal / dotcom

deprecated hebcal.com source code
https://github.com/hebcal/hebcal-web
21 stars 9 forks source link

Add Swagger/OpenAPI specification #19

Open catalandres opened 8 years ago

catalandres commented 8 years ago

By documenting the API in a standard format we could use cool tools like this one, which we could use to generate wrappers in a bunch of different languages.

Is it something that's in your radar? If not, I would like to give it a try.

mjradwin commented 8 years ago

Swagger would be great! We are generating the actual APIs from Perl (Jewish calendar and Shabbat APIs) and PHP (Hebrew Date converter API). Do you think we can use the swagger YAML editor to generate the swagger docs without needing to integrate into Perl? (Not sure if there is the notion of swagger "annotations" for Perl the way that is popular in Java).

If you would like to take a stab at this we would be delighted to include it.

catalandres commented 8 years ago

First attempt, an almost complete stab at documenting convert, here.

You can go to the Swagger editor to paste it and try it out. I think the documentation output is pretty cool.

I have coded this manually. There are integrations for Perl and PHP available, but my Perl is nonexisting and I don't know how these would fit with the current setup.

mjradwin commented 8 years ago

Looks superb. I only had to change the path from /converter to /converter/ to get the Send Request button to work correctly.

If you'd like to document /hebcal/ and/or /shabbat/ APIs, we can include those in the same documentation.