Feat: Include multiple $ref'd swagger files

[Javakky-pxv]

In my project, the routes file is long and there is a lot of content in each document that I would like to see in the Swagger UI.
I tried to include the response document in another file, referring to Using $ref, but the #definitions were not generated properly.
So we created a function to embed the JSON or YAML file in the project referenced by $ref.
Please check the README for the specific changes.

I thought about just scanning an external file and generating #definitions, but I thought it would be more convenient to have an embedding function, considering that I need to make a good reference to the main swagger.json.

[Javakky-pxv]

Sorry, but I'm tired today, and I'll provide a summary soon.

[Javakky-pxv]

@kailuowang
We would like to get your feedback on this feature first, when you are free 🙇

[Javakky-pxv]

Here is an excerpt from the README

No #definitions generated when referencing other Swagger files

By placing a json or YAML file in conf/${dir}/${file} and referencing it with $ref in a comment, the file can be generated embedded in swagger.json.

example conf/routes file.

###
#  summary: Top Page
#  responses:
#    200:
#      $ref: './swagger/home_200.yml'
###
GET     /            controllers.HomeController.index

example conf/swagger/home_200.yml file.

description: success

Of course, writing schema etc. will also be embedded.

Generated swagger.json.

{
  "paths": {
    "/": {
      "get": {
        "operationId": "index",
        "tags": [
          "routes"
        ],
        "summary": "Top Page",
        "responses": {
          "200": {
            "description": "success"
          }
        }
      }
    }
  }
  ......
}

See the following document for information on how to refer to other files by "$ref".

https://swagger.io/docs/specification/using-ref/

[kailuowang]

Looking great to me. I like the idea. 🙏

[Javakky-pxv]

@kailuowang
Thanks for your comment!
Can I ask you to review the code as well......? (Perhaps you have already reviewed it?)

[kailuowang]

Yes I did.

[Javakky-pxv]

Thanks!

[Javakky-pxv]

@kailuowang
Is it possible to get a temporary release with -SNAPSHOT to test the impact of this change on my repository?
We can deal with any problems, so PLAY2.8 is no problem.