API documentation with Swagger

[Riccardo Sirigu]

Has anyone tried to integrate Swagger with Lift, by any chance?

Play has support for Swagger out of the box, it will be cool for Lift to have it too 

[Antonio Salazar Cardozo]

Don't think anyone has had the opportunity, not. I'm not sure what's involved

even, to be honest. Would be happy to see anyone pick up that possibility, however.

Thanks,

Antonio

[Matt Farmer]

I have played with the idea of a Swagger generator of some sort before actually. Or even a runtime thing that parses a Swagger file and produces a RestHelper of some sort. I don't have a ton of time to investigate this right now but potentially could write up some thoughts somewhere.

--
--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

---
You received this message because you are subscribed to the Google Groups "Lift" group.
To unsubscribe from this group and stop receiving emails from it, send an email to liftweb+u...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Riccardo Sirigu]

It will be awesome.. 

I can contribute in some sort of implementation in my spare time

[Matt Farmer]

Hey Riccardo,

I haven't done much work here yet, but I've been experimenting with Scala Meta Macros at work a good bit. I think that there's a decent avenue toward a Swagger Generator using them. I need to collect my thoughts in more detail and throw together some example code. That said, I think that to start this kind of work would be a separate project instead of baked into the Framework.

I'm going to be working in the next day or so to figure out what I want my contributions for the 3.2 release to look like. Let me circle back with more thoughts after I've done that.

[Riccardo Sirigu]

Il giorno lunedì 10 luglio 2017 19:01:42 UTC+2, Matt Farmer ha scritto:

Hey Riccardo,

I haven't done much work here yet, but I've been experimenting with Scala Meta Macros at work a good bit. I think that there's a decent avenue toward a Swagger Generator using them. I need to collect my thoughts in more detail and throw together some example code. That said, I think that to start this kind of work would be a separate project instead of baked into the Framework.

I totally agree

 

I'm going to be working in the next day or so to figure out what I want my contributions for the 3.2 release to look like. Let me circle back with more thoughts after I've done that.

Great! 

[Matt Farmer]

Hi there,

Picking up the discussion here after having some time to think on how this might best be implemented.

I think I've decided that a traditional swagger code generator, like the ones that swagger-codegen uses, probably isn't a good option because it would only be used once in all practicality.

After researching the ways in which Play can be integrated with Swagger I think there are two choices here.

We could either:

Enable swagger spec generation from written code: I'm not quite sure exactly how we'd do this yet, but I can imagine some kind of data structure in the REST helper that could be used to generate a Swagger spec from the API.

or

Consume a swagger spec and generate a Lift RestHelper from it: I think this would be significantly easier. I'm thinking we'd use a macro to ultimately implement this. I think in code it would look something like...

@SwaggerAPI("/path/to/swagger/file")
object APIv1 extends RestHelper

... and the macro would take care of defining the API models and the rest of the actual API. To the rest of the Lift application the APIv1 object would look like a totally normally defined RestHelper.

What do y'all think about the above?

[Riccardo Sirigu]

Hi Matt,

what I personally find most useful is the automatic documentation generation provided by swagger-core.

The cool thing of the spec file generated by swagger-core is that you can make swagger-ui ingest it and make a beautiful and easy to maintain documentation of your Api.

Example here

Do you think it is possibile to annotate the RestHelper endpoints in order to produce a swagger specification file?

Consume a swagger spec and generate a Lift RestHelper from it I think it could be done in a step 2.. what do you think

[Matt Farmer]

> Do you think it is possibile to annotate the RestHelper endpoints in order to produce a swagger specification file?

I'm not sure. Unlike in many Java applications, the RestHelper endpoints aren't all first class objects. Further, PartialFunction (the type that the API boils down to) doesn't provide much in the way of ways to query it for information about where it's defined at. I'll have to think about how we might do this.

[Riccardo Sirigu]

I'm trying to come up with some sort of macro that parses the entire tree of a RestHelper and returns each endpoint found

@SwaggerAPI
object APIv1 extends RestHelper {

  serve {
    case "hello"  :: Nil Get _ => ...

    case "upload" :: Nil Post _ => ...
  }

}

I'll keep you updated