The README should more clearly explain the purpose of this gem

[anothermh]

I've used Grape off-and-on since 2016 and I've almost always used this gem to help generate Swagger docs. I'm currently using it in a project and my team relies on it every day.

Someone asked me what the gem actually does and I wasn't sure. I said I think it does something to enrich the docs with information from the entities. I went to the README and it says:

A simple grape-swagger adapter to allow parse representers as response model

Removing it raises an exception when generating our docs and the exception references an entity so I dug into the generated docs and I think that it's generating the definitions key:

{
  "definitions": {
    "Api_V1_Entities_User": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        }
      }
    }
  }
}

And tying that definition to the response body for that path:

{
  "responses": {
    "200": {
      "description": "OK",
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/definitions/Api_V1_Entities_User"
        }
      }
    }
  }
}

I looked at the source to double-check but there were no comments anywhere. I'm sure that given enough time to parse the source code of this and of ruby-grape/grape-swagger and ruby-grape/grape-entity I could figure out what the gem does but it seems easier to ask the authors if they can give some more detail on it.

I'm happy to create a PR for an updated README with more information if someone can give a clearer explanation of what this gem does, specifically:

1. The purpose of this gem is to ...
2. Without this gem your Swagger docs will be ...
3. With this gem your Swagger docs will be ...
4. This gem is required if ...
5. You should use this gem if ...

This information is probably spread out across a few different places like documentation from those other repos, issues from those repos, and discussions on the Google Group, but I think it would be helpful and more welcoming to new users to have the information in the README of this repo.

[kzaitsev]

@anothermh Hello, thank you, yes please send a PR.