ApiDOM defines parsers into the ApiDOM AST, does it provide a tool to go the other way?

[EricCrosson]

Hi there,

really neat project here! I'm trying to wrap my head around it still, and how I could leverage it. This line from the top-level README gives me a clear idea

It allows parsers to parse to a single structure and allows tool builders to consume one structure for all formats.

I can see there are numerous parsers defined that take code from OpenAPI, RAML, API Blueprint, etc, and parse into the ApiDOM AST (tree-sitter nation!) but once my data is parsed into that AST, I'm confused on what options I have to work with the data.

In my use case, I'm looking to generate an OpenAPI spec from a different contract. I figure it's just as easy to target the ApiDOM AST instead, which seems like it would grant RAML and API Blueprint export options as well, not to mention XML/YAML/JSON. But, I'm really only getting clarity from the docs on the other direction, namely, existing spec -> AST.

Thanks in advance for pointing out what I'm sure I missed in the docs 😀 Cheers!

[char0n]

Hi @EricCrosson,

I can see there are numerous parsers defined that take code from OpenAPI, RAML, API Blueprint, etc, and parse into the ApiDOM AST (tree-sitter nation!) but once my data is parsed into that AST, I'm confused on what options I have to work with the data.

Yes I can understand the confusion. We're still missing big chunks of our documentation, one of them being AST documentation. I've created an issue to track the lack of the documentation here: #1103. The issue contains links that might help understanding the underlying AST. Another options for working with AST is querying it: https://github.com/swagger-api/apidom/tree/main/packages/apidom-core#traversal

In my use case, I'm looking to generate an OpenAPI spec from a different contract. I figure it's just as easy to target the ApiDOM AST instead

I'd say it depends. If you plan to use some heavy metadata with ApiDOM AST than targeting the ApiDOM AST might be an option. But if you just want to generate OpenAPI definition from some other contract, generating OpenAPI directly (in JSON/YAML format) is IMHO a better and simpler option. Then ApiDOM can then be used to parse the generated OpenAPI specification, transform it to different specification and serialize in appropriate format.

like it would grant RAML and API Blueprint export

Yes it future it can. We currently don't have implementation for those languages (we call it namespaces). We have full implementation of AsyncAPI 2.x and OpenAPI 3.1 when I'm writing this comment.

not to mention XML/YAML/JSON

Currently ApiDOM comes with YAML/JSON parsing capabilities and JSON serialization capabilities. YAML and XML serializers are planned to be implemented in near feature (#134).

[EricCrosson]

@char0n, thanks so much for writing this out!

Based on this information, I will go the route of generating an OpenAPI 3.1 spec directly, and then later using ApiDOM to parse that JSON spec.

I appreciate the guidance and insight. Best of luck with this project -- I'll be sure to keep eyes on it 🚀