You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[ApiDOM Language Service](#apidom-language-service)
46
54
-[License](#license)
47
55
-[Software Bill Of Materials (SBOM)](#software-bill-of-materials-sbom)
48
56
@@ -107,7 +115,7 @@ You can install ApiDOM packages using [npm CLI](https://docs.npmjs.com/cli):
107
115
### Usage
108
116
109
117
Every package of the monorepo has an associated README file demonstrating its purpose and containing
110
-
usage examples.
118
+
usage examples. An overview of available packages is provided in the [ApiDOM packages](#apidom-packages) section.
111
119
112
120
### ApiDOM Playground
113
121
@@ -598,6 +606,112 @@ This very closely reflects how [Babel](https://github.com/babel/babel) works ([B
598
606
Their transform phase is our refract phase. The only difference is that when plugins are involved, our transform phase
599
607
requires 2 traversals instead of a single one. We can find a way in the future how to fold these 2 traversals into a single one.
600
608
609
+
## ApiDOM packages
610
+
611
+
### ApiDOM AST
612
+
613
+
[@swagger-api/apidom-ast](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ast) contains tools necessary for [syntactic analysis](#syntactic-analysis), which will take a stream of tokens and turn it into an AST representation. The AST represents the structure of input string in a way that makes it easier to work with. The package contains AST nodes for JSON and YAML 1.2 formats and comes with its own traversal algorithm convenient for traversing CST or AST.
614
+
615
+
### ApiDOM Core
616
+
617
+
[@swagger-api/apidom-core](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core) is a package that contains tools for manipulating ApiDOM structures. It provides a base ApiDOM namespace, predicates for all primitive and base namespace elements, and algorithms for transforming and handling ApiDOM structures. The available algorithms allow for transcluding, merging, copying, traversing and transforming ApiDOM structures into its different forms.
618
+
619
+
### Retrieving ApiDOM Elements
620
+
621
+
It is possible to evaluate [JSON Pointer](https://github.com/swagger-api/apidom/tree/main/packages/apidom-json-pointer), [Relative JSON Pointer](https://github.com/swagger-api/apidom/tree/main/packages/apidom-json-pointer-relative) and [JSONPath expressions](https://github.com/swagger-api/apidom/tree/main/packages/apidom-json-path) against ApiDOM structures. A successful evaluation returns the corresponding ApiDOM Element at the specified location.
622
+
623
+
### ApiDOM Namespaces
624
+
625
+
The namespace packages provide ApiDOM namespaces for specifications, consisiting of a number of elements implemented on top of primitive ones. The refractor layer in each namespace allows to transform JavaScript structures or generic ApiDOM into elements from that specific namespace. The elements can be traversed using the `visit` function provided by [apidom-core](https://github.com/swagger-api/apidom/tree/main/packages/apidom-core) package.
The parser packages provide parser adapters for specifications in JSON and YAML formats, allowing to transform them into generic ApiDOM or specific ApiDOM namespace.
644
+
645
+
The base parser adapters support [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-json) and [YAML 1.2](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-yaml-1-2) formats. They are responsible for [lexical and syntactic analysis](#parse-stage), transforming the provided string into a generic ApiDOM structure. These base adapters are extended in parser adapters for specifications, enabling parsing of definitions directly into the ApiDOM namespaces for those specifications.
646
+
647
+
Available parser adapters for ApiDOM namespaces:
648
+
649
+
- API Design Systems - [JSON](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-api-design-systems-json) / [YAML](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser-adapter-api-design-systems-yaml)
[@swagger-api/apidom-parser](https://github.com/swagger-api/apidom/tree/main/packages/apidom-parser) consumes any parser adapter with compatible shape and provides a unified API for parsing. It contains logic of mapping a source string to appropriate media type and a source string with media type to appropriate ApiDOM namespace.
658
+
659
+
### Advanced ApiDOM manipulations
660
+
661
+
[@swagger-api/apidom-reference](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference) provides algorithms for semantic ApiDOM manipulations. It contains components enabling parsing, resolving, dereferencing and bundling.
662
+
663
+
The [parse component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#parse-component) implements the default parser plugins, enabling parsing for files located on local filesystems and on the internet. It can parse provided definitions into generic ApiDOM structure or into one of the ApiDOM namespaces.
664
+
665
+
Available parse strategies:
666
+
667
+
- JSON format
668
+
- YAML 1.2 format
669
+
- Binary format
670
+
- ApiDOM - JSON
671
+
- API Design Systems - JSON / YAML
672
+
- Arazzo 1.0.1 - JSON / YAML
673
+
- AsyncAPI 2.x.y - JSON / YAML
674
+
- OpenAPI 2.0 - JSON / YAML
675
+
- OpenAPI 3.0.x - JSON / YAML
676
+
- OpenAPI 3.1.0 - JSON / YAML
677
+
678
+
The [resolve component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#resolve-component) provides file resolution and external resolution sub-components. File resolution contains plugins allowing to read files located on local filesystem and on the internet, and provide their content. External resolution resolves external dependencies of a document using a specific external resolution strategy, providing a set of resolved references as a result.
679
+
680
+
Available external resolution strategies:
681
+
682
+
- ApiDOM
683
+
- AsyncAPI 2.x.y
684
+
- OpenAPI 2.0
685
+
- OpenAPI 3.0.x
686
+
- OpenAPI 3.1.0
687
+
688
+
The [dereference component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#dereference-component) transcludes referencing elements (internal or external) with referenced elements, using a specific dereference strategy.
689
+
690
+
Available dereference strategies:
691
+
692
+
- ApiDOM
693
+
- AsyncAPI 2.x.y
694
+
- OpenAPI 2.0
695
+
- OpenAPI 3.0.x
696
+
- OpenAPI 3.1.0
697
+
698
+
The [bundle component](https://github.com/swagger-api/apidom/tree/main/packages/apidom-reference#bundle-component) allows to package up resources spread across multiple files in a single file (Compound Document) using a specific bundle strategy.
699
+
700
+
Available bundle strategies:
701
+
702
+
- OpenAPI 3.1.0
703
+
704
+
### ApiDOM Language Service
705
+
706
+
[ApiDOM Language Service](https://github.com/swagger-api/apidom/tree/main/packages/apidom-ls) provides language processing for ApiDOM supported languages for editing experience. It adheres to the LSP Protocol and can therefore be used via LSP Server wrapper, providing editing capabilities to various editors and IDEs. It provides validation, documentation, definitions, completion, semantic highlighting and dereferencing for supported specifications.
707
+
708
+
ApiDOM Language Service supports:
709
+
710
+
- AsyncAPI 2.x.y
711
+
- OpenAPI 2.0
712
+
- OpenAPI 3.0.x
713
+
- OpenAPI 3.1.0
714
+
601
715
## License
602
716
603
717
ApiDOM is licensed under [Apache 2.0 license](https://github.com/swagger-api/apidom/blob/main/LICENSES/Apache-2.0.txt).
0 commit comments