search

silkapp / rest

Packages for defining APIs, running them, generating client code and documentation.
http://silkapp.github.io/rest
390 stars 52 forks source link

Swagger integration #115

Open finlay opened 9 years ago

finlay commented 9 years ago

Hi

We are building an API and would like to use the Haskell rest library. One requirement is to produce swagger style documentation and/or discovery service.

I notice there is a rest-discovery branch https://github.com/jcberentsen/rest/tree/rest-discovery, and wonder what the status of that is ? Perhaps I could contribute to that branch ?

Regards Finlay

bergmark commented 9 years ago

Hey,

That branch contains a new package that provides an api resource for discoverability. It works but is mostly a proof of concept, there is still work to be done before it would make sense to release it. It may have to be updated to be compatible with the latest versions of the other rest packages (nothing major, i think).

We are not working on this at the moment so if you want to help out that would be great!

I'm not familiar with Swagger but I'll try to answer any questions you have.

Cheers

finlay commented 9 years ago

Hi

Thanks for responding. I have a go at creating a swagger-consistent view of a rest api.

Let you know how I get on!

Finlay

On Sun, 19 Apr 2015 at 08:39 Adam Bergmark notifications@github.com wrote:

Hey,

That branch contains a new package that provides an api resource for discoverability. It works but is mostly a proof of concept, there is still work to be done before it would make sense to release it. It may have to be updated to be compatible with the latest versions of the other rest packages (nothing major, i think).

We are not working on this at the moment so if you want to help out that would be great!

I'm not familiar with Swagger but I'll try to answer any questions you have.

Cheers

— Reply to this email directly or view it on GitHub https://github.com/silkapp/rest/issues/115#issuecomment-94199338.

MaxDaten commented 9 years ago

@finlay I'm currently thinking about this, too. What is your current planned approach? Take a swagger specification and generate the rest-api or the other way around, take the rest api in Haskell and just provide the swagger discovery and documentation?

Swagger is for me a very concise rest spec and a good contract between api implementer and api user, even in the yaml format. I must admit, I would prefer writing the api spec in Swagger and let generate the necessary haskell backend skeleton. This would allow some nice opportunities: For example someone without Haskell skills (e.g. front-end dev) can read the spec and can make proposals via push-requests.

But I know, this is not easily done. But maybe this is the space to discuss different approaches.

finlay commented 9 years ago

Hi @MaxDaten

My intention was to produce swagger from the haskell rest api. However, I didn't get very far. Other things got in the way. Still interested in the general idea though.

I think that having a tool that generates a haskell skeleton from a swagger spec would be ideal. Then have it produce swagger spec from the haskell as well to confirm that it has worked.

I got a bit delayed with the swagger specification. Should be easy enough though to write a swagger parser that produces a haskell data structure. From that generate a haskell module.

What do you think ?

F

superduper commented 9 years ago

Hi there! Are you guys familiar of https://github.com/twittner/swagger? I think some TemplateHaskell voodoo could help generate code for silkapp/rest or other rest libraries.