We're using a library that does not handle object properties named "id", as it confuses them with the "id" schema keyword (which is not actually legal in that position so that's very much a bug). We should move to a conforming implementation, and then we can drop our "ID" means "id" workaround.

There are at least to issues that prevent doca from working on MS windows

1. The schema.js file generated by doca init contains wrong pathes, ie

import { fromJS } from 'immutable';
export default fromJS([
  require('..\cart.json'),
  require('..\product.json')
]);

There is a backslash missing, so the JSON files won't be found during build

2. The npm scripts build and build:nojs don't have a valid syntax for windows CMD. You must set an environment variable by set SOMEVAR=value. Further more this is a separete command so you'll have to add an additional && before the call to webpack like for instance

"cleanwin": "rmdir /S /Q build",
"buildwin": "npm run cleanwin && set NODE_ENV=production && webpack --config webpack/config.prod.withjs.babel.js && del build\\static-*", 
"buildwin:nojs": "npm run cleanwin set && NODE_ENV=production && webpack --config webpack/config.prod.nojs.babel.js && del build\\static-* && del build\\app-*.js"

I get this error on running npm start command

D:\doca\example\documentation>npm start

[email protected] start D:\doca\example\documentation
node webpack/index | NODE_ENV=development node src/server

'NODE_ENV' is not recognized as an internal or external command,
operable program or batch file.

npm ERR! Windows_NT 6.1.7601
npm ERR! argv "C:\Program Files\nodejs\node.exe" "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" "start"
npm ERR! node v6.9.4
npm ERR! npm v3.10.10
npm ERR! code ELIFECYCLE
npm ERR! [email protected] start: node webpack/index | NODE_ENV=development node src/server
npm ERR! Exit status 255
npm ERR!
npm ERR! Failed at the [email protected] start script 'node webpack/index | NODE_ENV=development node src/server'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the example-api-documentation package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! node webpack/index | NODE_ENV=development node src/server
npm ERR! You can get information on how to open an issue for this project with:
npm ERR! npm bugs example-api-documentation
npm ERR! Or if that isn't available, you can get their info via:
npm ERR! npm owner ls example-api-documentation
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR! D:\doca\example\documentation\npm-debug.log

attaching npm-debug.log
npm-debug.zip

There are multiple packages as a part of this project. Let's add a diagram explaining how they relate.

Currently we're using a PHP-ish ":", but given that hyper-schema is written using RFC 6570 URI Templates we should stay consistent with that.

There are definitely hyper-schema features from draft-04 that we will not support as they were removed in the next draft for lack of use case, or replaced with more straightforward alternatives (which we may actually support as extensions to draft-04, but that's for other issues to document).

Off the top of my head, I see no reason to support:

• "fragmentResolution"
• "pathStart"
• the "root" link relation
• special behavior for the "describedBy" link relation

I'm more ambiguous about the whole changing the "href" URI base with "self" links. The later "base" keyword is far more straightforward, and the "self" change is a SHOULD anyway. "Because the feature got tossed in the next draft" is probably one of the better reasons to ignore a SHOULD, but feel free to speak up if you need this feature. (Although really, I'll be surprised if anyone even remembers it exists).

There may also be some validation keywords like "not" that are hard to use effectively in documentation that we might skip.

Having spent a while comparing doca with api-console, some things look rather nice about it.

Example page (may take a while to load) https://anypoint.mulesoft.com/apiplatform/popular/#/portals/organizations/52560d3f-c37a-409d-9887-79e0a9a9ecff/apis/5502/versions/5487/pages/30295

In the instance where valid values have commas, it becoms unclear if a comma is a breaking character or part of the value.
Example:

I don't know if quotes or some sort of highlighting would be better.

We are currently collecting requirements internally and via issues here for doca, and will be putting together a loose road map for the project. We should publish some form of that on the wiki here for community feedback and input. I'm filing this mostly to let people know it's a thing :-)

Of the top of my head, without factoring the requirements-gathering that's just started, I expect something along the lines of:

• 0.x releases will be strictly compatible, but not a long-term support (LTS) release line
  • We will do a bit more with this to fix easy but important issues
  • No guarantees at this time that any specific thing will be fixed in 0.x
• 1.0 release will involve minor breakage, easy migration, and 1.x will be an LTS release line
  • Need to define what LTS means for doca
  • Within the 1.x line, we will maintain compatibility
  • We will need this to continue to document Cloudflare's v4 APIs
  • Other JSON-base HTTP APIs that are not strictly RESTful can depend on this
  • Hopefully we can automate the schema edits needed for migration
  • 1.x will probably not support JSON Schema drafts after Draft 04, unless someone wants to take that on and write PRs for it
  • Fixing the nonstandard usage of "rel": "self" is the kind of breaking change compared to 0.x that we'll do here
  • Issues like #10 (standards-compliant URI Template variables) need more work on the JSON Schema spec side, and will likely not be addressed in 1.x
• 2.0 release will be based on JSON Schema Draft 06 and will be more hypermedia-oriented
  • Hopefully this will also drive ideas for a JSON Documentation Schema specification (json-schema-org/json-schema-spec#136)
  • Migrating from 1.x to 2.x will likely require manual changes to schemas
  • Priority will be given to fully RESTful APIs (strict compliance with HTTP semantics, etc.)
  • Supporting other API approaches may depend on community contributions
  • This will probably be an experimental release line, which when stable can cut over to a 3.0 LTS release line

Take all of the above with a grain of salt, as I literally made it up while typing without consulting anyone else.

If you have specific asks for future releases, please file them as their own issues. If you have more general comments, questions, or concerns, please comment here. When we publish the road map on the wiki I'll ensure everything is addressed in some way and close this issue.

While developing a theme, I've been only making static versions of the documentation. Now I'm ready to do a lot more work on this theme, I wanted to try hot reload, as I worked out I COULD actually run a node server on our dev machines.

I tried to run with my modifications. It loaded and supplied content, but the page was blank. I tried using the example usage found in the readme, from scratch. Exactly the same.

First I worked out that localhost was hard coded. I had to change this for running from our servers.
Now app.js returns contnet, but the application doesn't seem to initalise or something.

The response from app.js is as follows:

<!DOCTYPE html>
<html lang="en-US">
<head>
    <meta charset="utf-8" />
    <title>Example API Documentation</title>
    <meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no" />
    <link href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet" />
</head>
<body>
    <div id="app-root"></div>
    <script src="http://not-local-host-but-a-local-address.com:8000/build/app.js" type="text/javascript"></script>
</body>
</html>

Any thoughts on what might not be working quite right? I can't seem to find any further problems (other than just flat out showing me a blank page =/)

For reference, the static build process works just fine, no problems there!

If I have a bollean type which has a default value of true or false, empty string is displayed.

When creating a theme with multiple css files in the styles folder, not all of them are always pick up and included.

Noted at #39 (comment)

Refresh node modules versions. Webpack 1 -> Webpack 2 can be especially tricky, we might need to update json-schema-loader and json-schema-example-loader as well.

People should be able to play with our documentation generated by doca-boostrap-theme (based on cart.json and item.json).

It is currently implemented mostly like "properties" but with the additional ability to merge into the results of an adjacent allOf/oneOf/anyOf. However, per the spec, "properties" already behaves this way (adjacent schema keywords are effectively an additional branch of an implicit allOf anyway). And "additionalProperties" takes a single schema, not a set of names.

This is a json-schema-example-loader issue in object-definition.js

It's possible to specify requests/responses of other media types, but we need to design a way to usefully convey that in the generated documentation.

We don't need to support documenting the details of such requests and responses, just that they exist and use a specific media type (e.g. text/plain, text/x-yaml, application/octet-stream, etc.)

@mahtin this is relevant to your interests.

If you have both required and optional params for a route, the column widths for the two tables can differ if you do not wish to use the same fixed width for all object definition tables.

The comment about comments in cloudflare/json-schema-loader#2 reminded me of this.

It's easier for humans to write and read YAML than JSON. And writing JavaScript as basically JSON + comments is also something I see a lot. We should allow schemas in either format.

"examples" will be an official part of JSON Schema in Draft 6, so we should use it in place of our current "example". Note that "examples" is always an array, and per the spec, any "default" can be treated as an additional example.

As per the most recent commit - cloudflare/json-schema-loader@2e75f22 - this now breaks for webpack 2.

The docs specify that callback should be invoked with a second argument that looks like a sourcemap, not an arbitrary type. https://webpack.js.org/api/loaders/#this-callback.

We are able to use 0.0.3 and it works, but you might want to specify webpack version in the readme.

Currently doca (both the default bootstrap theme and the cloudflare theme) hides the core resource representation by default, requiring the user to find and click a "show" button. The individual requests and responses are given the most prominent position.

I'd like to flip that, and put the main focus on the core representation. For each allowed method, the documentation should focus on any differences from standard HTTP semantics. Where the request or response is identical to the representation, we do not need to keep repeating the representation docs.

If linting needs to pass for Pull Requests to be accepted, it would be awesome to see this in the PR and save everyone some time.

Looks like it's possible by using something like https://www.npmjs.com/package/travis-github-lint-status

I may try make a PR for this, but don't know if it will work or not (as in, if it will run the travis ci config file from the PR side)... one way to find out!

Is there any reason why you are lower casing the keys of the object by default?

I've started trying to work on a theme.

I checked out the doca theme at the bootstrap commit, as it will allow us to apply our styling and colours over the top of bootstrap like the rest of our application.

I wanted to update the version of bootstrap, and remove the use of using a cdn in favour of bundling the bootstrap css in with the rest of the minified file.

I added bootstrap as a dependancy of the new theme, however it seems that I can't actually add bootstrap to my theme from node_modules, as the theme doesn't have a webpack step.

I tried to add the bootstrap css as per example shown at https://github.com/theodybrothers/webpack-bootstrap, however of course it does not work because bootstrap is a dependancy of the theme and not of doca itself.

It seems the only way this would work would be if I were to copy the css required to the styles folder for the theme as part of the build process. This seems somewhat sub-optimal to me.

Am I missing something really obivous here? I'm still new to using node and webpack.

I realise I could just change the version number in the existing cdn URL, but what if I want to add other dependancies? I'm looking at adding a few via bower, but then wanting to use bower components in a webpack setup would create the same disconntion problem, where webpack is run at the doca level and only files in the style folder of the theme are added to the end result.

If I'm totally getting the wrong idea here, please do say. I've spent the good part of a day trying to figure this out and I'm a tad demorilised.

In json-schema-example-loader, we infer the type from the first entry in the enum.

This is not correct- the "enum" keyword can mix instance types. To convey a type restriction, schema authors must use the "type" keyword.

In the absence of "type" we may want to try to detect the types, but we need to examine all elements in the enum.

I've been trying to evaluate document generators over the past few days.
api-console from Mulesoft generates from RAML, which supports headers. Also with RAML, you can specify authentication.
The API I'm working on expects keys in headers. It would be great to be able to be able to define this somehow. Such a definition would need to impact on the CURL request example (Which I really like btw).

While doca is not a validator, "not" can be used to express conditions that should appear in documentation. This was requested for doca's predecessor project at cloudflare/json-schema-docs-generator#13.

We definitely do not want to just document the schema under "not" the same way we do schemas that express positive constraints. There needs to be some thought on what is actually useful for human-oriented documentation here, as opposed to programmatic validation.

@swamikevala if you are still interested in this with doca, can you go into your use case a little bit more? The example given seemed like it was trying to do something like:

{
    "allOf": [
        {"required": ["foo"]},
        {"not": {"required": ["foo"]}}
    ]
}

where the first entry was shown as a "$ref". If this is what the "$ref" resolved to, it is an impossible schema- any object that has a "foo" property will pass the first and fail the second, and it's the other way around if there is no "foo" property. So perhaps I am misunderstanding your use case?

the overall doca system is (at least) four repositories:

• cloudflare/doca (this repository)
• cloudflare/doca-bootstrap-theme
• cloudflare/json-schema-loader
• cloudflare/json-schema-example-loader

While technically different issues impact each of these, would it perhaps make more sense to turn off issues and the wiki on the other three, and add a note at the top of their README referring readers to this repository for feedback and comprehensive documentation?

Particularly now that we have a few outside folks who have expressed interest and/or filed issues.

@toekneestuck : thoughts?

I was trying to view the code for doca and associated modules at a specific release. Turns out there's no view to do this on npm or using npm, other than to npm install that version you want to view. If you tagged releases on github, it would make it easier to find the state of the code at a specific release in a more meaningful way. =]

I'm building a documentation pipeline with doca being a large part of it.

I've hit a snag. Your docs say you only run doca init once to bootstrap the project. Making the same call again just throws an error. However, there's no doca function to update and/or pull in new schemas from the parent folder.

The only way I can see this currently working is to remove the documentation folder, and re-run doca init any time I add or remove any schemas.

That in itself is not a problem, but I have to run npm install before I can run npm build when in the documentation folder. npm install takes a bit of time...

It would be great if there could be a new command, like doca update to simply update the list of schemas doca should use.

I'm happy to try and make a pull request, but I don't write node, and I wouldn't know how to write tests for this change either.

First, great tool! Thanks for your hard work on this!

I'm able to run the tool and start a node server with the example documentation, but I want to get the static files for my documentation.

Following the directions in the readme. I ran npm run build, but it fails...

npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     npm run clean && NODE_ENV=production webpack --config webpack/config.prod.withjs.babel.js && rm build/static-*

I then installed webpack globally. I had to then clean the project, re-init, install, and then the command worked.

It would be good to add to the documentation that webpack is required to be globally installed, or if possible, make that not a requirement.

Thanks.

Other applications or tools may want to write to the configuration file provided. They may also want to read from it using another language!

It sure would be easier if it was json a json file.

We would copy "required" from the LDO level into the parameters object (even if it was undefined), instead of just using the one in "schema".

Posted a PR before filing the issue: cloudflare/json-schema-example-loader#5

@Relequestual (or anyone) were you relying on this? We will bump the version number before publishing this, but I might have some other fixes before then.

doca uses "rel": "self" within the "schema" and "targetSchema" schemas more or less like an internal "$ref" to the containing resource's schema. But "rel" is properly only a keyword in the link description object, so we should switch this to a normal "$ref"

object-definition.js in json-schema-example-loader uses else-ifs and ||s when examining schemas for these keywords, meaning that only one will be respected (allOf if present, then oneOf, finally anyOf if neither of the others are present).

I currently have a part of my docs which looks like the following:

I'm going to try using "oneOf" with two different data types, seperating the strings and numbers, and using min/max for numbers, but I don't know how that will come out in the docs (if at all).

Nope. That didn't work. CLOSE though...

The real problem is that doca doesn't seem to support oneOf (and possibly other ...Of keywords) as the value of property keys.

Can we have a changelog please? =]
http://keepachangelog.com

I would like my object definitions to appear in the order found in the schema files.
It makes sense to have the definitions for fields to be in the same order as the example object.

I notice the current CF documentation has this issue.
It looks like a theme issue from my limited understanding.

@handrews I know objects are unordered, so is this actually a JSON Hyper Schema issue? If we want JHS to be used to generate documentation, then do we need a field order array?

I'm investigating the posibility of using https://facebook.github.io/immutable-js/docs/#/OrderedMap, but really I'm not even sure how to create my own theme... Yes the docs say "fork this project" but then what? I don't want to publish it to npm... It's like I should already know what to do after I fork it.

Currently, if an object property is itself an object, the whole object schema is just shown as a JSON string instead of displaying some sort of nested table.

The workaround is to reference the nested object in an "allOf" or "oneOf", but this should work with inline nested objects as well.

This is similar to cloudflare/json-schema-docs-generator (@swamikevala) from our old docs system.

"default": false

doesn't show up in docs

but

"default": true

does

"default": "false"

as a workaround works but that's not correct

I wanted to post an issue or two about https://github.com/cloudflare/doca-bootstrap-theme, however it's not possible.

I've started work on an updated version of the bootstrap theme.
The recent changes you have made make it no longer a bootstrap theme.

I would guess you may want to create a new theme repo for the new theme, and migrate code over, and then make that the default theme for doca. I would like to submit a few stylistic and functional changes for the bootstrap theme. I'll continue to work on my own version till you work out how you'd like this to work.

The theme docs say the easiest way to create a new theme is to fork the project, but provide no further information.

It seems unlikely that I'm expected to publish an npm module every time I make a change. I really don't know how I'm supposed to develop and test a new theme. The docs expect I should already know how to do this...

The current Cloudflar API documentation looks great. I like the sidebar being seperate.
Currenty with doca, when I scorll, I then can't see the menu. A UI thing for sure.

The root of my POST schema is an array object type. The resulting parameters for the request are blank in the finished documentation.

schema => {
  type => 'array',
  items => {
    type => 'object',
    properties => make_properties(stuff),
  }
}

vs

schema => {
  type => 'object',
  properties => make_properties(stuff),
}

Sorry I've just realised I've given this in perl hash format rather than json, but you get the idea.

The new "base" keyword in hyper-schema can take over what the doca config file's "baseUrl" currently does.

It could be useful to colour code the HTTP request types. I would guess this is a theme issue, but to do it may require some change in the code and theming options, I don't know.

It's possible for there to be multiple types for a property.
Only the first type is shown in the documentation when the type is an array.
EDIT: I though that only the first type was shown, but both are, just without any sort of spacing... so I have a "stirngnull".

This is especially important if you want any fields to be nullable, as you must have a data type of null in addition to what you want for non null values.