search

cloudflare / doca

A CLI tool that scaffolds API documentation based on JSON HyperSchemas.
BSD 3-Clause "New" or "Revised" License
228 stars 36 forks source link

Better to be able to load JSON schema files in runtime #79

Closed shenghu closed 6 years ago

shenghu commented 7 years ago

Is it possible not to compile JSON schema files. Instead, load schema files in runtime, especially from a URL?

handrews commented 7 years ago

@shenghu what do you mean by runtime? Do you want to use this to browse dynamically generated documentation in some way? Or are you talking about interacting with the API (making calls over HTTP) based on the schemas? In both cases, the answer is "not currently, but it is something I'm actively looking into."

If neither is what you have in mind, could you go into a bit more detail?

Either way, I would love to hear more about your use cases.

shenghu commented 7 years ago

@handrews I mean whether doca can provide a similar online editor like http://editor.swagger.io/ which can load schemas from a url. If editor is not easy, a viewer is mostly wanted to allow user to view json schema in a nice way.

Today, Doca is good. It would be better if it needn't compile schema files, but simply load ones from anywhere.

BTW, another benefit of online viewer/editor is that users can embed it as an iframe to their page.

shenghu commented 7 years ago

BTW, I create this theme, doca-events-api-theme, (just start) which is to generate non-REST document, e.g. events. The theme can group schema files by category. category is not standard in JSON schema. But let's see if there is a better way.

handrews commented 7 years ago

@shenghu I will respond to your other points later, but just so that you know I've been changing the output of json-schema-example-loader (eventually it will not be so different from the standard schema, just with some convenience data added). The current doca-bootstrap-theme does not use this new version of the example loader, so you might want to look at the example loader's changelog in its repository to see if you would like to build your theme on newer code.

There is a roadmap document in this repository outlining where I'm going with things, although it's not a firm commitment.

handrews commented 7 years ago

I would love to have an editor like that, but don't see a way to staff that work from within the company right now. Of course if anyone wants to work on it as an open source contribution I'd be happy to coordinate :-)

I am also an author/editor of the JSON Schema draft specifications, and my focus right now is on publishing draft-07. Future doca work will probably prioritize moving to that draft and hopefully making it easier to extend the system with things like editors.

handrews commented 6 years ago

@shenghu there is now a new doca back-end (and hopefully soon a new set of themes) at the JSON Schema Tools monorepo. The new doca is @cloudflare/doca, to keep it separate from the existing doca, which is still usable but will not be update except by volunteer contributions.

The new back-end outputs valid JSON Schemas (optionally with extensions), so the interface for building themes is now different. But standard JSON Schema tools can now be used with the output schemas in case you want to further process them before display. Or build an editor :-)

We believe that aligning Doca with the JSON Schema standard for both input and output will make it easier to support and extend the project, and draw on the larger JSON Schema community.

I'm closing this because this repo is now more or less dormant, but feel free to open an issue at the new repo.