Allow disabling generation for message body

[kylef]

This PR adds a generateMessageBody option, which when set to false will prevent generation of message body in the OpenAPI 2 and OpenAPI 3 parsers. The option has no effect on message bodies defined on OAS 2/3 via examples or similiar constucts. This is option is only applicable to the cases where generation of message bodies occur.

Missing Changes

• Missing tests in OpenAPI 2 parser
• Missing changelog entries
• Missing documentation

[opichals]

Using this option shouldn't all the adapters be consistent in that they do not provide message body example and only provide the convenience API to get it on-demand?

[opichals]

Should the property name generateMessageBody apply to the messageBodySchema too?

I don't think it should as it is the spec that is directly provided (or derived if MSON is used).

[opichals]

Missing convenience API for generating message body element. Where should this belong?

httpRequest/httpResponse elements?

[kylef]

Using this option shouldn't all the adapters be consistent in that they do not provide message body example and only provide the convenience API to get it on-demand?

Yes, this PR only tackles OpenAPI as those adapters are written in this repository. Propergation to Drafter,Protagonist,drafter.js is required for API Blueprint support of the feature. There's more work involved here.

Should the property name generateMessageBody apply to the messageBodySchema too?

I don't think it should as it is the spec that is directly provided (or derived if MSON is used).

In API Blueprint, MSON produces dataStructure, and the dataStructure is used to generate messageBody and messageBodySchema. That work can be delayed in similiar way to this PR.

It is possible in API Blueprint to explicitly define messageBody and messageBodySchema, in those cases they will always be present in the parse result. These options are only going to affect "generated" elements.

Perhaps worth us creating a JavaScript function that takes dataStructure element and references and produces JSON Schema (v4, v8 etc). That also means that tooling such as Dredd that only supports JSON Schema v4 can pin to specific version. Generated JSON Schemas can be large and noisy too, as due to referencing some schemas can contain the same definitions section as other data structures.

[opichals]

It occurred to me that not having the 'ramdom' body example in the parseResult is good but it would be good to drop the 'randomnes' completely as otherwise the documentation machine column would potentially still render different stuff upon every reload of the app which is very confusing to users.

[honzajavorek]

Should the property name generateMessageBody apply to the messageBodySchema too?

I don't think so. In API Blueprint examples and schemas can be separately either inferred or described explicitly. They're two different beasts. In OAS the author can also provide an explicit example, or/and gives us "OAS schema", from which we can generate whatever schema we need (e.g. JSON Schema draftXYZ).

tooling such as Dredd that only supports JSON Schema v4...

Working on it 🚀

[kylef]

It occurred to me that not having the 'ramdom' body example in the parseResult is good but it would be good to drop the 'randomnes' completely as otherwise the documentation machine column would potentially still render different stuff upon every reload of the app which is very confusing to users.

@opichals I'd propose that instead of using randomness in generated message bodies we would use the valueOf logic. valueOf is used in OAS 3 parser at the moment, and an equivilent is used on API Blueprint for MSON. valueOf produces consistent results and does not create random data. The outlyer here is OpenAPI 2 which produces random examples in the parser.

[kylef]

@honzajavorek agreed, I think we can implement two options generateMessageBody and generateMessageBodySchema both defaulting to true (to maintain existing behaviour) -- parse times may be lower with them disabled, and "validate" may disable them by default (depending on the parser and if additional validations occur when generating them).

Defaults:

• generateSourceMaps: false
• generateMessageBody: true
• generateMessageBodySchema: true

[kylef]

I've done a quick set of metrics to understand the parsing times and the resultant parse result size. This test is for OAS 2 only and with a single description document (i'd imagine other parsers behave very differently, and the amount of requests/response and size of them can have impact on these results).

Sizes

$ du -h .
544K	oas2.source.json
 18M	oas2.parse-result.json
9.3M	oas2.parse-result-without-body.json
 11M	oas2.parse-result-without-schema.json
2.9M	oas2.parse-result-without-body-and-schema.json

Times

$ time npx fury oas2.source.json > oas2.parse-result.json
       11.11 real        12.52 user         0.52 sys

$ time npx fury oas2.source.json > oas2.parse-result-without-body.json
        1.84 real         2.15 user         0.18 sys

$ time npx fury oas2.source.json > oas2.parse-result-without-schema.json
       10.60 real        12.21 user         0.45 sys

$ time npx fury oas2.source.json > oas2.parse-result-without-body-and-schema.json
        1.64 real         1.87 user         0.15 sys

[kylef]

Similiary for API Blueprint an MSON heavy (but small structured document) with Drafter:

$ du -h apib*
960K	apib.parse-result-without-body-and-schema.json
2.1M	apib.parse-result-without-body.json
4.1M	apib.parse-result-without-schema.json
4.1M	apib.parse-result.json
 80K	apib.source.apib

$ time ./src/drafter -f json apib.source.apib  > apib.parse-result.json
       17.10 real        15.86 user         0.71 sys

$ time ./src/drafter -f json apib.source.apib  > apib.parse-result-without-body.json
        8.23 real         7.66 user         0.33 sys

$ time ./src/drafter -f json apib.source.apib  > apib.parse-result-without-schema.json
       15.57 real        14.63 user         0.58 sys

$ time ./src/drafter -f json apib.source.apib  > apib.parse-result-without-body-and-schema.json
        0.44 real         0.41 user         0.01 sys