Swagger documentation for BodyParam and Responses with JSON models generated from case classes by reflections

[smeagol74]

This patch allows to document JSON models from case classes with Swagger like this example:

package quickstart.action

import java.util.Date

import xitrum.FutureAction
import xitrum.annotation.{POST, Swagger}
import xitrum.util.SeriDeseri

@POST("api/test")
@Swagger(
	Swagger.JsonBody("request", "This is request model", Test.RequestType),
	Swagger.Response(200, "Success", Some(Test.ResponseType)),
	Swagger.Response(201, "Success", Some(Test.ResponseArrayType)),
	Swagger.Response(404, "Not found")
)
class Test extends FutureAction {
	override def execute(): Unit = {
		SeriDeseri.fromJValue[Test.Request](requestContentJValue) match {
			case Some(req) => // do something useful
			case None => // reply 404 or something
		}
	}
}

object Test {

	case class Sub(subValue: Option[Int])

	case class Response(value: String, sub: Sub)

	case class Request(integer: Int,
	                   long: Long,
	                   float: Float,
	                   double: Double,
	                   string: String,
	                   boolean: Boolean,
	                   dateTime: Date,
	                   optional: Option[String],
	                   list: List[String],
	                   seq: Seq[Sub],
	                   obj: Sub
	                  )

	val RequestType = Swagger.arrayOf[Request]
	val ResponseType = Swagger.valueOf[Response]
	val ResponseArrayType = Swagger.arrayOf[Response]
}

And this code will produce following swagger.json

{
  "swagger" : "2.0",
  "info" : {
    "title" : "APIs documented by Swagger",
    "version" : "1.0-SNAPSHOT"
  },
  "basePath" : "/",
  "paths" : {
    "/api/test" : {
      "post" : {
        "operationId" : "test",
        "parameters" : [ {
          "name" : "request",
          "in" : "body",
          "description" : "This is request model",
          "required" : true,
          "schema" : {
            "type" : "array",
            "items" : {
              "$ref" : "#/definitions/Test.Request"
            }
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "Success",
            "schema" : {
              "$ref" : "#/definitions/Test.Response"
            }
          },
          "201" : {
            "description" : "Success",
            "schema" : {
              "type" : "array",
              "items" : {
                "$ref" : "#/definitions/Test.Response"
              }
            }
          },
          "404" : {
            "description" : "Not found"
          }
        }
      }
    }
  },
  "definitions" : {
    "Test.Request" : {
      "type" : "object",
      "properties" : {
        "integer" : {
          "type" : "integer",
          "format" : "int32"
        },
        "long" : {
          "type" : "integer",
          "format" : "int64"
        },
        "float" : {
          "type" : "number",
          "format" : "float"
        },
        "double" : {
          "type" : "number",
          "format" : "double"
        },
        "string" : {
          "type" : "string",
          "format" : ""
        },
        "boolean" : {
          "type" : "boolean",
          "format" : ""
        },
        "dateTime" : {
          "type" : "string",
          "format" : "date-time"
        },
        "optional" : {
          "type" : "string",
          "format" : ""
        },
        "list" : {
          "type" : "array",
          "items" : {
            "type" : "string",
            "format" : ""
          }
        },
        "seq" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/Test.Sub"
          }
        },
        "obj" : {
          "$ref" : "#/definitions/Test.Sub"
        }
      },
      "required" : [ "integer", "long", "float", "double", "string", "boolean", "dateTime", "list", "seq", "obj" ]
    },
    "Test.Sub" : {
      "type" : "object",
      "properties" : {
        "subValue" : {
          "type" : "integer",
          "format" : "int32"
        }
      }
    },
    "Test.Response" : {
      "type" : "object",
      "properties" : {
        "value" : {
          "type" : "string",
          "format" : ""
        },
        "sub" : {
          "$ref" : "#/definitions/Test.Sub"
        }
      },
      "required" : [ "value", "sub" ]
    }
  }
}

You may want to load that json to Swagger Online Editor to check how the documentation looks like.

This patch supports simple case classes as models (not sure about inheritance and other advanced features), Seq, List, Set as array types, Option for non-mandatory fields.

[ngocdaothanh]

Can you remove this file? I guess it's only for a particular editor thus should not be committed.

[smeagol74]

This is cross editors configuration for code autoformatting supported by rather a lot of IDEs and editors: https://editorconfig.org/#download

The idea was to allow to share the same configuration between different project developers. But if you insist, I'll remove it.

[ngocdaothanh]

What's the purpose to add _? to the name? Should we simply name it required?

[ngocdaothanh]

Anyone can freely change any file, so let's remove User, Date, and Time.

[ngocdaothanh]

Please remove _ prefix because is ugly. Add private if it's private.

[smeagol74]

@ngocdaothanh , I applied all the fixes. Also I rebased my patch over the current master and squashed into the single commit. I did not removed the .editorconfig yet, hope you will decide to leave it in project as useful.

[ngocdaothanh]

👍 Thanks, I've commented at the new PR. The PR is very cool, I'm just requesting for some changes in coding style, so that the new files look consistent with existing files.