stoplightio
feat(formatters): add markdown formatter
Checklist
- [x] Tests added / updated
- [x] Docs added / updated
Does this PR introduce a breaking change?
- [ ] Yes
- [x] No
Screenshots
Example of output (used as test case) ⬇️ ℹ️ The links in the table are just here to demo the documentationUrl usecase, they lead to nowhere.
| Code | Path | Message | Severity | Start | End | Source |
|---|---|---|---|---|---|---|
| operation-description | paths./pets.get.description | paths./pets.get.description is not truthy | Error | 1:0 | 10:1 | ./src/__tests__/fixtures/petstore.oas2.yaml |
| operation-tags | paths./pets.get.tags | paths./pets.get.tags is not truthy | Warning | 11:0 | 20:1 | ./src/__tests__/fixtures/petstore.oas2.yaml |
| rule-from-other-ruleset | paths | this rule has no documentationUrl so the rule code is not a link | Warning | 21:0 | 30:1 | ./src/__tests__/fixtures/petstore.oas2.yaml |
Additional context
A Markdown output is a nice middleground between HTML (can be rendering in a lot of contextes, for example Github) and textual. As HTML, markdown support some interactivity (links), which make use of the documentationUrl to quickly acces more information on a given error.
Possible usecases:
- Autogenerated output examples: if your Spectral ruleset is in Github (or similar), it is easy to run and update examples of spectral output against a few set of example OAS each time a rule is changed (on merge). With a Markdown output, those would be easy to read (as Github support Markdown rendering), providing always up-to-date and readable output examples.
- Non-regression tests: building on the autogenerated output examples, a pre-merge pipeline could ensure that OAS examples always generate the same (expected) Spectral output. That would give you more confidence that a change in a rule has the effect you expect. While it's possible to do that with existing formatters (ex: JSON), Markdown provide a better reading experience in Github.
Note: a new utility function getDocumentationUrl.ts could be reused in other formatters to provide links for rules (or rulesets) that have a documentationUrl set up.
I've created a small function in markdown.ts to create the markdown table, instead of using an external dependency
original message:
👋 Apparently, one of my dependencies (markdown-table-ts) use the "??" coalescing operator, so is not compatible with node 12. The alternative is markdown-table, which is ESM only so does not play well with Jest.
❓ Do you plan to drop support for node 12 soon (end of life was 2 years ago). Or should I work on ESM support for Jest (could be a rabbit hole of funky configuration), or should I implement my own markdown table "renderer" (so more code to maintain here).
:tada: This PR is included in version 1.4.0 :tada:
The release is available on @stoplight/spectral-formatters-1.4.0
Your semantic-release bot :package::rocket:
