Use Jackson to produce JSON-Schema

[swagger-api]

Use Jackson to produce JSON-Schema

[fehguy]

I've looked into this. Problem is, using jackson's schema generator will not allow the use of the optional (and quite helpful) annotations. For example:

http://petstore.swagger.wordnik.com/api/pet.json

Shows a "Pet" object with allowable values, required fields, and descriptions. I don't see how we could ingest that easily without essentially seriously hacking the jackson json schema code

[fehguy]

I think the best solution to this and #46 is to make the schema generation pluggable. There will one implementation, based on the swagger-generated model. In configuring that provider, we can pass the namespace for package inclusion. Another provider can be implemented using Jackson.

[webron]

Okay, I did some digging, and this is what I've come up with.

If I understand you correctly, you're missing a few fields in the JSON Schema that Jackson generates such as "description", "allowableValues" and perhaps others. There are two issues here, as far as I can tell:

1. Jackson's JSON schema generation is limited, and Tatu states so on his own: http://markmail.org/thread/bcji7hkneq3oquzy - As such, support for various JSON Schema attributes is limited.
2. According to http://swagger.wordnik.com/spec - Swagger is supposed to conform to the 3rd draft of the JSON schema, however, that's not the case. For example, the attribute "allowableValues" is used instead of "enum" which according to the spec is equivalent to that.

So it seems we end up bare-handed on either side. If we use Swagger's mapper, we'll need to create some proxy class or perhaps add additional annotations on top of Jackson's so that it'll create the right model. If we use Jackson's mapper, we get a lean schema with no sugar.

I agree that it making the schema generation pluggable is a good idea, but it seems I'll still have ways to go before getting a fully descriptive usable schema.

[fehguy]

Two approaches, hopefully they will solve the problem. Going to add the @JsonIgnore support in the swagger schema generator. Also going to add support for Jackson schema which at first won't take advantage of all swagger annotations.

I have both working, going through and making sure all the tests pass, and limitations are known.

[fehguy]

OK the limitation with the Jackson-based schema generator is pretty massive--that is, complex object properties cannot be "linked" to other complex types. So this:

{
  "id":"ComplexObject",
  "properties" : {
      "names" : {
         "type":"array[string]"
      }
   }
}

will work fine. But when the names is complex (say User), we'll get this:

{
  "id":"ComplexObject",
  "properties" : {
      "names" : {
         "type":"List[object]"
      }
   }
}

The schema can contain the details of the object but it will violate the schema flattening that swagger requires and enforces. Ideally we would link directly to the object contained in the array, and that object could be shared in other methods:

{
  "id":"ComplexObject",
  "properties" : {
      "names" : {
         "type":"List[User]"
      }
   }
},
{
  "id":"User",
  "properties" : {
      "first" : {
         "type":"string"
      }
   }
}

So we would have to auto-generate some new model names to support the "anonymous" inner complex objects. That's fugly.

[webron]

That's definitely fugly - going to have a look at it.

[fehguy]

You can see the pluggable json schema generation here:

https://github.com/wordnik/swagger-core/tree/1.1.0-spec

This doesn't solve the problem but it gives some options. More soon on this wild frontier...

[fehguy]

Now model introspection is pluggable:

https://github.com/wordnik/swagger-core/blob/master/modules/swagger-core/src/main/scala/com/wordnik/swagger/jsonschema/JsonSchemaProvider.scala

Now you can write a class which reads a model via Class[_] and emits a DocumentationObject. Will add a jackson version after some issues with jackson are fixed.

[p14n]

Hi there,

It looks as if this is not yet pluggable (as in the ApiPropertiesReader instantiates this object). Is that correct?

Any plans on opening it up - I'd like to write my own implementation.

Thanks,
Dean

[fehguy]

It should be, that's a bug. Will address it...

[p14n]

Much appreciated!

[ben-manes]

It would be nice if the schema generated included constraints by scanning for JSR-303 annotations. Alternatively registering a catalog of the model schema definitions and referencing them by a label. I'm using json-schema-2-pojo to generate the Java classes (Jackson + JSR-303) from the schema, so Swagger's generation is redundant work in this situation.

[fehguy]

While the schema generation is now pluggable, json schema proved to be too generic to support the codegen use cases. So for now, it's not supported in swagger.