schema class method to get OpenAPI schema

[okuramasafumi]

Abstract

OpenAPI is a common way to define API schema. I think it's convenient if we could export the schema of the resource into OpenAPI compatible JSON (or Hash) so that we can develop API first and then tell other developers how that API works.

Example

It works like below:

class FooResource
  include Alba::Resource
  attributes id: Integer, name: String
end

FooResource.schema

The output of schema will look something like below:

{
  "type": "object",
  "required": [
    "id",
    "name"
  ],
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
  }
}

Discussions

We can provide type information that's required by OpenAPI, but we cannot provide requirement information now. I'm considering adding on_nil option to attributes call so that with on_nil: :raise it's required attribute.

[trevorturk]

I don't use OpenAPI, but I think this sounds like a nice idea.

I wanted to share a couple of gems that might show some "prior art" about defining schemas: https://github.com/jgaskins/primalize and https://github.com/voxpupuli/json-schema -- just in case these are helpful to review.

As for the on_nil, I think that's a good option. You could also consider using required: true as https://github.com/rmosolgo/graphql-ruby/ does. You could also consider adding required_attributes as you have attributes already, but this may be strange to use. I'm not sure what would be best, but I wanted to offer some brainstorming ideas in any case. I think the on_nil will be good if you choose that way, absolutely.

Thanks!

[oskargargas]

That's a great idea! It could be used as a part of bigger toolset to generate OpenAPI specification for whole API.