Repository navigation
Output rendering: proposed plan #954
DrSatyr
started this conversation in
New Features
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
This is my proposed plan for the output of openapi-diff in 3.0.0. It gives rendering work one common direction, and I'll use it when reviewing rendering PRs.
Contributions to the plan are welcome: comment below with corrections, missing cases, or better ideas, and I'll update the plan.
Related: #777 · Issues: Render capabilities, #562, #523, #506, #508, #627, #355
Roadmap
--statefixRenderAPI, migration notes--group-by, more formatsWhere we are today
Each of the 5 renderers (Console, Markdown, HTML, Asciidoc, JSON) walks the result tree on its own (~2,000 lines). So each one shows a different subset of the changes:
--jsondumps the whole internal tree, including both full specs (1.1 GB for one diff)Goals
Core idea: one change list, many formats
The result tree is turned into a flat list of changes once. Renderers only format that list; they never read the tree or the spec objects.
One change:
locationis a list of typed steps (parameter,requestBody,response,mediaType,property,items,header, …), not a display string. Renderers use it to group changes.componentsays where the changed schema is defined. Withoperation+location(where the change was seen), every record has two addresses, so changes can be grouped by operation or by model. If a$refis renamed (Pet→PetV2), it holds the old and the new ref.resultuses today's names (incompatible,compatible, …), so nothing is renamed.operationis empty for changes outside operations (e.g. security schemes, top-level extensions, later webhooks).ruleandresultare owned by Clarify Breaking/Non-Breaking Changes and Improve Configuration Mechanism #724.Output formats
Text formats (Console, Markdown, HTML, Asciidoc) all show the same content. Markdown, HTML and Asciidoc are built-in templates (see "Templates"); Console stays Java (tree lines, line width, colours):
Grouped output
The list is flat, but the text output doesn't have to be. The library builds ready-made views from the one list, and each renderer picks the view it needs:
changes()byOperation()locationprefixbyComponent()component.pathprefix, each change with its operationsAll views come from the same records, so totals and the overall result are always the same.
By operation. Records for one operation:
query limitstatusowner›name404200› application/json ›nicknameRendered (Console):
By component. One change in
Pet, used in a request and in a response:Changes in inline schemas have no component; they appear under an "inline schemas" group in this view.
Both views are part of the 3.0.0 API. In 3.0.0 the built-in renderers use
byOperation();byComponent()is for Java users and custom renderers. A CLI/Maven option to pick the view (e.g.--group-by) can be added in 3.x without changes to the record, the views or the renderers.--htmlvs--html-detailed), or a "breaking changes" summary at the top.Templates
Users can render the report with their own template (#355):
eq,if, partials, …).result,summary, spec info,changes,byOperation,byComponent. The data includes ready-made values (e.g.incompatible: true,locationText), so templates need no logic for common cases.{{> group}}).templateFile+templateOutputFileName.Example:
JSON (
--json), replacing today's tree dump:{ "formatVersion": 1, "result": "incompatible", "summary": {"incompatible": 1, "compatible": 4, "metadata": 2}, "changes": [ { "rule": "request.enum.decreased", "result": "incompatible", ... } ] }formatVersionchanges only on breaking changes to the format.ChangedOpenApi.--stateprints onlyno_changes | compatible | incompatible, as documented (#508).Java API (3.0.0, breaking)
ChangeReport= overall result + change list; built fromChangedOpenApi.String render(ChangedOpenApi); renderers no longer close the stream.Stability rules (so 3.x stays compatible):
locationstep types, newchangekinds and new rule IDs are not breaking changes. JSON consumers must ignore unknown fields; this is stated in the JSON Schema docs.markdown,html,asciidoc) follow the same rules.ChangeReportand its views, never onChanged*classes, so engine changes don't break custom renderers.How this fits with the other 3.0.0 plans
rule+result, doesn't decide themresultin the change list; must equal today's result for existing specstypes,string | null)const)Rule IDs at the start: today's
incompatible.*property names without the prefix (request.enum.decreased). Changes without a property today get a new ID. The full catalog is owned by #724.Phases (3.0.0)
$refonChangedSchema(the engine knows it, but doesn't keep it today); test: everyChanged*class produces records. Verdicts taken from the tree, no rule changes.--statefix.byOperationandbyComponentviews; template support (Handlebars, template data,--template,--print-template, Maven parameters); Markdown, HTML, Asciidoc as built-in Mustache-syntax templates and Console ported to the views, one PR each; cross-format test.RenderAPI, migration notes, README examples.3.x: CLI/Maven option to pick the view (
--group-by), more formats (TeamCity #849, GitHub annotations, JUnit; possibly as built-in templates), layout polish.Dependency note: templates use current Handlebars.java (4.5.x), which needs Java 17. 3.0.0 requires Java 17 anyway (#777).
Order with the other plans
All reactions