Joining efforts [#2812801]

I am the maintainer of the JSON API module. One of the current experimental features of the module is to create the schemas for the auto-generated resources. I was wondering if we could join efforts in this task, given that this module seems to have that same goal.

At the moment, the schema generation in JSON API is very rudimentary and just a PoC. But we are using the docson library to display pretty docs for the schema in a Drupal page.

This module seems to be more mature in the schema generation area, and it supports all core formats. There are plans to include JSON API as part of core during this next release 8.3.x. Would it make sense to add JSON API to the list of supported formats that schemata adds support to?

Comments

Comment #1

6 October 2016 at 05:13

e0ipso created an issue. See original summary.

Comment #2

Grayside CreditAttribution: Grayside at Phase2 for Norwegian Cruise Line commented 13 October 2016 at 05:27

Hi @e0ipso,

What are you looking for this project to provide JSON API? Is the missing piece just the rendering of the schema as part of an HTML page? I have some initial thoughts on #2773009: Have a "web display" of schema resources but it feels like a schema to HTML rendering module should be a dedicated project. I'm open to incubating it as part of this one to help the pieces more easily move along.

Comment #3

e0ipso

Catalan

Can Picafort

CreditAttribution: e0ipso as a volunteer and at Lullabot commented 14 October 2016 at 17:38

For me it would be sufficient to just have the schema to be generated for the JSON API REST entities.

For the web visualization, we are using docson in the jsonapi_docson, which is an example of what you can do with the JSON schemas with little effort.

JSON Schema is a fantastic way of describing data structures, however it's is a bit limited to auto-document REST APIs. For that, Open API seems to be emerging as the leading standard. My question is, how much of this work would be possible to leverage to produce an Open API document (formerly Swagger)? Is there anything that can be done so a future http://drupal.org/project/openapi can depend on Schemata? Even more, would you consider adding Open API support inside of Schemata?

Comment #4

Grayside CreditAttribution: Grayside at Phase2 for Norwegian Cruise Line commented 14 October 2016 at 20:48

JSON API

If all you need is JSON Schema output initially, we're pretty much there. My project team and I have been nudging #2751325: All serialized values are strings, should be integers/booleans when appropriate along as a precursor to tagging a release.

If you want schemas that define JSON API payloads via JSON Schema, then Schemata or JSON API need a jsonapi_json_schema module to create a new serializer. In Schemata, we have hal_json_schema which extends from json_schema to create HAL-specific customizations, a similar pattern would probably work for JSON API.

Open API

My next major roadmap goal is Open API #2773007: Support Swagger, incubating it inside Schemata seems good to me, and appropriately within the mission of Schemata. I'm generally taking an approach of keeping entity-driven schema generation under one project umbrella to get things moving and facilitate creating the "schema" objects used by the serialization process. Getting OpenAPI off the ground will require creating a new Schema object that describes the site overall, and something that can do REST route introspection. The JSON Schema stuff would then be embedded as part of the payload descriptions.

Once Open API spec generation is sorted, I was going to investigate swagger-to-html solutions and http://swagger.io/redoc-openapi-powered-documentation/ as something that might be more customizable and embeddable than Swagger UI.

Currently I'm focused on field testing and polishing the JSON Schema bits.

Comment #5

e0ipso

Catalan

Can Picafort

CreditAttribution: e0ipso as a volunteer and at Lullabot commented 28 October 2016 at 05:23

I just merged #2821554: [FEATURE] Deprecate jsonapi_docson in favor of Schemata. to move this along.

Do you think that given that JSON API, according to #2757967: API-first initiative and this blog post, is planned to be in core in the future it makes sense to add support for it inside of Schemata?

If you don't think it does, I will create a separate contrib jsonapi_schemas to host the code that produces the schemas.

Comment #6

Grayside CreditAttribution: Grayside at Phase2 for Norwegian Cruise Line commented 28 October 2016 at 20:55

Let's host inside schemata. As this continues to evolve I anticipate spinning out the provider modules as separate projects.

Comment #7

tedbow

he/him

English

Ithaca, NY, USA

CreditAttribution: tedbow at Acquia commented 8 June 2017 at 13:25

Version:

» 8.x-1.x-dev

re #4
Just wanted to post here that there is the OpenAPI module

Working on getting that module to use this module #2870393: Remove openapi_json_schema submodule and add dependency on Schemata module

I personally think it would be good to keep OpenAPI a separate module.

While I waiting on a couple issue here to be committed I working on branch of OpenAPI that works with Schemata: http://cgit.drupalcode.org/openapi/log/?h=8.x-1-jsonapi_refactor

This branch includes generate docs using Swagger UI for REST and JSON API(though they could use some work)

I am also testing out using ReDoc instead here https://github.com/tedbow/openapi_redoc
From my reading if we ever wanted to include generated docs in a distribution like Contenta the ReDoc license, MIT, would be compatible with hosting on Drupal.org and Swagger UI's license, Apache version 2 would not.