Open lorddaedra opened 1 year ago
Some notes about design:
it's up to you what format to choose
One of the possible solutions here - just use swagger.yaml
you already own:
.yaml
data files to this repository, lago-docs
repository, combine them together and commit as swagger.yaml
to lago-openapi
repository (ex. using github workflows in lago-docs
repository) so on every change in docs data files it will commit changes to lago-openapi
repositoryYou can even add some fields with x-lago-
prefix to this parts, which will be ignored for OpenAPI generation but used for docs generation.
The easiest way here is using yaml format but you can use any other format and make this yaml parts dynamically.
`.xml` parts ("source of truth") ---------> `.yaml` parts ---------> swagger.yaml
\---------> docs
Problem
Docs are readable by humans but has not optimal format to be readable by different automatic tools. Docs is "source of truth". We need use these data for different types of validators. Of course, we should not break UX for humans.
Proposed Solution
Instead of markdown tables like this
you should use yaml, toml, json, xml or similar formats for storing data to construct such tables. (it's up to you what format to choose, vote for your preferred data format here: https://lago-community.slack.com/archives/C0499C4UMT7/p1678643968709619)
After that it will be possible to add Lago's API contract validators to OpenAPI schema repository.
From technical side: you use .mdx format (which allows to use Markdown tables and typical ts/js components, which may load data from files.)
https://mdxjs.com/docs/what-is-mdx/
I do not see technical troubles here to replace Markdown tables to something more useful for parsing by validators.
(Of course, it's possible to parse even Markdown tables with
, spaces and<SomeShit></SomeShit>
inside, but it make result less predictable and lead to errors. Why it's a bad idea (html regex parsing, meme): https://stackoverflow.com/a/1732454)