Swagger support

[mgreenwood1001]

Quick Hack to support Swagger v2.0 (incomplete, still in progress)

public static void main(String args[]) {
        port(8080);
        Spark.swagger()
            .host("127.0.0.1:8080")
            .info(new SwaggerInfo()
                .contact(new Contact().email("[email protected]"))
                .description("Verification of swagger documentation")
                .license(new License().name("Apache v2.0")
                    .url("http://www.foo.com"))
            )
            .basePath("/")
            .version("1.1.0")
            .swaggerVersion("2.0");

        get("/foo",
            new RouteDocumentation()
                .description("Root end point")
                .consumes(new Payload().json().xml())
                .produces(new Payload().json().xml())
                .operationId("foo")
                .summary("Generates foo"),

            (req, resp) -> "foobar"
        );

    }

Produces:

{
  "swagger": "2.0",
  "info": {
    "description": "Verification of swagger documentation",
    "contact": {
      "email": "[email protected]"
    },
    "license": {
      "name": "Apache v2.0",
      "url": "http://www.foo.com"
    }
  },
  "host": "127.0.0.1:8080",
  "basePath": "/",
  "paths": {
    "/foo": {
      "get": {
        "summary": "Generates foo",
        "description": "Root end point",
        "operationId": "foo",
        "consumes": [
          "application/xml",
          "application/json"
        ],
        "produces": [
          "application/xml",
          "application/json"
        ]
      }
    },
    "/swagger/v2.json": {
      "get": {
        "summary": "Swagger JSON v2 Documentation endpoint",
        "produces": [
          "application/json"
        ]
      }
    }
  },
  "version": "1.1.0"
}

[ruurd]

Is it possible to do an annotation approach here instead? I think that is cleaner.

[mgreenwood1001]

@ruurd the lambda could be annotated -- let me know if you intended something else, otherwise I can make those changes.

Here's an example:

        @RouteDocumentation(tag = "tagName", description = "end point description")
        @RouteParameters({
            @RouteParameter(name = "name", required = true, type = string, in = path),
            @RouteParameter(name = "id", required = true, type = integer, in = path)
        })
        Route route = (req, resp) -> "hello " + req.params("name") + " -> " + req.params("id");

I don't see a way this can be done in the method call itself -- meaning the put(...), get(...) delete(...), etc. call itself, at least not in a way I found possible - thus you'll need to declare the lambda in advance of the HTTP verb invocation and then pass that as a parameter from which the swagger content can interrogate the annotations.

[ruurd]

OK I think this is workable. Thanks.

[mgreenwood1001]

@ruurd annotations can be applied to local variables generally but the reflection inspection available at run time does not allow for the modeling of these annotations at the local variable level, so they're basically useless unless you want compile time process the code using something like Checker... because of the lambda's there really isn't a way to do this with annotations I can think of....

[n3wtn9]

+1 Is it possible push the ball forward on this?

[noahbetzen-wk]

Is this still being considered? Possible for the future 3.0 release?
#1102
#1105

[ericblue]

I realize this issue has been open for quite a while, and not certain if there are plans still to release v3.0 or patch support for 2.x. If anybody is interested, I recently built on some code examples from back in 2016 and updated to support Swagger annotations using the lambda route declaration syntax. The code used to parse and support swagger annotations are minimal, and uses org.reflections and JAX RS with Spark 2.9.4.

An example project using this approach is at: https://github.com/ericblue/spark-starter-basic