https://github.com/frolovdev/anyspec
As far as you can see, Anyspec is a domain-specific language for writing API specs with main compilation target to OpenAPI. But what does it mean and why does it exist?
In Osome, we used https://github.com/Ajaxy/tinyspec . The main idea of Tinyspec is a DSL on top of OpenAPI spec, or in other words “write less, do more”. The OpenAPI format is a little bit verbose for manual writing, so this tool was invented to accommodate. So Osome, as a company, took a chance with Tinyspec some time ago. But this solution brought with it a lot of problems:
Parsing is based on regexp and doesn't output any AST. It's hard to maintain and extend such a solution. But it's also brought to us non-determinism in terms of the language design; in other words, no one knows for sure answer for sure which combination of symbols and newline's Tinyspec can parse and which can not. On an everyday basis, we face such problems. Here's the proof
The second problem is that Tinyspec doesn’t follow the specification of either OpenAPI 2 or OpenAPI 3, so we can’t use any other open source technology to work with our specs, because they always get a syntax error if they try to parse invalid OpenAPI specification.
And last but not least, the author of this lib isn’t interested in supporting or developing this library and doesn’t support new version of OpenAPI spec 3 or higher.
Based on such prerequisites, I decided to make a solution for a company with the same functionality but with much better architecture, the right design and with full compatibility with the open API standard. To achieve this, I pitched this idea to one of my friends, and we began work on implementation and design.
We decided to implement linter without compilation output as the first milestone of our project to bring value to the company as quickly as possible. The beneath of such idea was that if we have an AST, we can easily implement printer (formatter) and compiler or transpiler. To achieve this, we implemented:
The architecture of the language was mostly inspired by python, golang, and especially by Graphql-js.
https://www.figma.com/file/D2MQKMxhxflBd2Pxw8di9D/spec?node-id=0%3A1
Here’s an overview of the initial planning roadmap, which ended up not being implemented. It’s a step-by-step high level roadmap from the current situation to the expected ideal outcome.
On the first screen, you can see that we take specs and provide them to custom existing lint. This can only track simple rules like trailing comma where you don't need an abstract syntax tree; we take linted spec and put it into the TinySpec library which produces an open API spec file, and as a final step we take this open API file and pass it to our custom library which creates typescript types and SDKs, which our clients (frontend app) can use.
In the next step, we add our new linter, which goes like a separate step on ci and produces errors.