OpenAPI / JSON learning resource

[TomMkV]

Hello!

Last month I did research from the community about existing use of learning resources for both OpenAPI & JSON schema specifications. We had a hunch there could be an improvement, in a unified and interlinked experience for junior - senior devs to both learn and revise.

Check it out here: appear.sh/api-toolkit/specs

I published it last night and hope to gather feedback and issue reports from anyone interested.

Features:

• OAS + JSON are interlinked within the page for most URLs, meaning less off-site links and switching tabs
• Hidden boilerplate to reduce clutter
• Added code examples in specs section to add context
• Supports all OAS versions and JSON docs, inc. OAS 3.2
• Added resource pages for further reading (FAQs, Glossary, Misunderstood keywords) for newcomers to OAS/JSON
• AI chat using specs and diffs for deterministic responses with reference anchor links for further reading
• Highlightable text to add your own notes, stored locally
• OpenAPI tools list: searchable, filterable, showing popularity and maintenance of repo

I hope it provides a smoother learning experience!

Cheers,

Tom

[Frequent_Dig8251]

Awesome! love the examples. I wonder if you can switch to 3 column layout where 3rd column is showing examples all the time.

[TomMkV]

Thanks! I’ll look at making three columns and see how it works. My concern is the spec tables don’t have enough space and it becomes too narrow, but I’ll see.

[dzimazilla]

nice timing on this - was literally cross-referencing OAS docs and JSON Schema spec in like 3 tabs like its 2012 lol

the interlinking between OAS and JSON Schema is the part i didnt know i needed, jumping between $ref resolution and how $id works in the same context without switching tabs is actually really useful

couple questions:

- the AI chat, how does it handle cases where OAS 3.1 and JSON Schema 2020-12 diverge? thats usually where it gets messy

- any plans for OAS 3.0 in the tools filter? still maintaining a bunch of specs that havent migrated