json schema visualization

[wedens]

It would be great to have some json schema visualization like in swagger-ui for example.

[mgogov]

+1

[mgogov]

Are there any plans and timeframes for potentially including such a feature in the api-console?

We recently started redoing our old fashioned API docs using RAML (pretty much work-in-progress) and deploying the api-console with it and asking users for feedback.

While the recent commits have greatly improved the usability and look'n'feel of the console, documenting the JSON response structure can sometimes not work that well with more complex APIs.

Our use case is that we're trying to heavily use all RAML and JSON Schema means of DRYing up our code, such as the $ref directive in JSON Schema v4. We try to extract common patterns in JSON Schema snippets which we can then reuse in similar resources and extend those only with the differences, such as:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "live response schema.",
  "allOf": [
    {
      "$ref": "doc/raml/schemas/train/updates.json#/updates"
    },
    {
      "properties": {
        ... extensions ...
      }
    }
  ]
}

With the current behaviour of the console, the user doesn't see most of the response structure JSON Schema definition which means they don't have the means to see the $ref-ed part whatsoever.

1) A good first improvement would be to have the api-console show fully resolved versions of the JSON Schema defs without any $ref's, so that the user can actually see the full response documentation. I believe this is also referenced in #59

2) As @wedens has suggested, doing further visualisation such as using swagger-ui like features or docson (live demo) or similar can only greatly improve the UX for users.

If 1) and 2) are not planned at all, what would be a potential workaround? Would you accept a pull request implementing such a feature if you find it useful?

Best regards, Martin

[tonyleigh]

We have exactly the same need. Some of our APIs return Resources with quite some complexity and detail in them - the Schema documentation is just as important (in some cases more so) than the endpoint spec.

The current solution of treating the schema as a flat string means that the schema displayed inline with the RAML is next to useless to the API consumer as we factor out all the common parts and use the $ref to refer to them.

We are currently building out parallel tooling to pull out the schemas from the RAML bundle and provide interactive documentation separate to the API documentation. This is useful as it allows us to show the higher level model rather than jump in at the endpoint list - but it would be great if the endpoint details could show the similar detail around the schema. We will look to share when completed.

@mgogov - did you make any progress on schema documentation?

Would be good to hear if the project was open to pull requests on this.

[adamgotterer]

+1 for this functionality

[thizzle]

+1 Breaking down the properties of the schema a la swagger-ui (live demo) would be incredibly useful.

[sichvoge]

Fully in for that. +1000

@mgogov do you know how well docson is maintained?

[mgogov]

@tonyleigh, @sichvoge:

We couldn't get any response on multiple questions I asked here so we ended up implementing our own solution on this in our forked version of the API console: https://github.com/transportapi/api-console/commit/35ab1b91f19b4bf07774046368688cb36055ab51

The logic in the commit: 1) recursively fetches the $ref entries from the JSON Schemas 2) merges the allOf entries into one 3) makes the JSON Schemas open by default

We thought integration with docson would be too hard, so we implemented just the plaintext expansion of the schemas but this can be a good step for future upgrades.

An example of the result can be seen in our work-in-progress RAML docs:

• deployed here
• our RAML file
• a more complex schema $reffing another schema
• scroll down to expanded JSON schema for the /uk/train/station/{station_code}/{date}/{time}/live.json endpoint to see the expanded result with no $refs and merged allOf entires

@sichvoge, not sure whether this solution (or an extract) would be interesting as a PR to be merged in the main codebase? We've got other ideas on how to solve this as well like pre-deployment server-side preprocessing, etc, but it's good to sync these suggestions with the maintainers and so far we've failed to get their attention.

[sichvoge]

@mgogov:

Thanks for your response. I am one of the maintainer and maybe you remember that we actually met in real live couple of months ago at APICon in London :)

To answer your questions:

If 1) and 2) are not planned at all, what would be a potential workaround? We definitely think that resolving the schemas is something that must be done so that the console can show the full schemas or basically better - only if needed. I don't think the ref's should be resolved if not needed. That means if you don't press the expand button it will only show the ref - if you expand it will show you the schema etc. The problem doing everything at once is that you might get into a really bad recursion at some point by pointing back to a parent schema, etc. There are some corner cases we have to think about.

Would you accept a pull request implementing such a feature if you find it useful? Yes we would accept a pull request. There are some condition before we merge any PRs though. You need to add tests, when it is something in the UI you need to add an imagine, and you need to sign the our CLA. You can find the full version here. Don't be confused, it's the CONTRIBUTION file for the api-designer, but it is basically the same for the console.

That said, I am in for a combination of 1) and 2), and I think both needs to be implemented as one (based on the recursion problem I mentioned - only a graphical view could do the collapse/expand).

[tonyleigh]

@mgogov, @sichvoge

Your changes look good to me for the Console, I'd love to see that merged into the trunk. However I agree with @sichvoge that there needs to be some protection against recursive schema references - something we have run into - and our docson solution doesn't handle well.

It would be nice to do the expansion on user selection in the UI, but I guess that would complicate the solution. Perhaps a simple depth protection on the recursion in getRefs() would prevent serious problems.

Our situation is slightly different, we are utilising the MuleSoft Anypoint hosted platform, so don't have the option of forking the Console code base. (Well we could, but that would defeat the point of utilising the platform).

Our solution to this problem is to publish the schemas on a separate web server using docson. We have a script running in the background to take the RAML + Schemas from the Anypoint platform and store in git, so have hooked into this to publish the schemas on our web server.

We are utilising the Notebooks heavily to explain the API and the use cases it supports, so have a page describing the Resource Model which links to both the docson schemas and the schemas directly. This is working well for us, though it would be nice to be able to embed the docson HTML rendering directly into the Notebooks.

[sichvoge]

@mgogov @tonyleigh

I would be really keen to see a good solution and let it merge into the current console - which would also mean it goes into the MuleSoft's Anypoint Platform at one point. So let me know if there is any progress.

[gideonaa]

+1 for this feature. It'd be even better if it were integrated into the Anypoint platform.

[sichvoge]

@gideonaa - if that feature get's into this version, it will most probably go into AP as well.

[fellipebrito]

+1

[gideonaa]

@sichvoge Thanks!

[sichvoge]

Let's wait for @mgogov as he is the man of honour :)

[aquamatthias]

+1 - this is needed!

[clintfoster]

+1

[FredMessinger]

+1

[ahernandez1129]

+1

[sichvoge]

Hope we reach 100 +1 :P On a serious note, we are already thinking on supporting that. I'll keep you updated on what ever that looks like. We hear you ;)

[maltzj]

+1

[RaphC]

+1

[sameshit]

+1

[elinger]

+1

[wolfgangkirchler]

+1

[auramirea]

+1

[nektru]

+1 :)

[vanadar]

any update to share ?

[sichvoge]

There is no update yet. We are currently updating the console to support RAML 1.0 RC2. We definitely hear you and we think we can provide an even better experience with the console in general in the future. All the feedback we've got will be consolidated and we will definitely think about what the best approach will be.

BTW, I'd suggest anyone to up-vote the original post using "Add your reaction", instead of adding a new comment with +1 :)

[Saboosh]

+1, Sorry @sichvoge but I dont see an "add your reaction" button

[jarrodek]

This was introduced in version 5