mimirsbrunn
mimirsbrunn copied to clipboard
hove-io
Add an openapi (fka swagger) description of bragi.
I've attempted to describe all API endpoints and their parameters in a documentation.
This could replace the table with TODO's in the README.
It is documented using openapi3 standard. In YAML. From this description, other formats can be compiled, like the HTML version that I included as example for now.
The openapi yaml file can be used in many tools, including postman, insomnia, or swagger UI.
E.g. https://petstore.swagger.io/?url=https://raw.githubusercontent.com/berkes/mimirsbrunn/feature/openapi-doc/documentation/openapi.yml#/default/autocomplete will show the documentation for bragi in a browser.
Is this usefull for you? If so, there are some things that need to be done and decided:
- [ ] Do we want a (generated) html version that I included in the git-repo?
- [ ] if yes, a CI job that builds this file should probably be included, since compiling it, requires node-js tooling, which we cannot expect all devs to install and run.
- [ ] Is there a public bragi server running that we can use as demo next to the localhost:4000 one?
After that, the descriptions and examples in the documentation can probably be improved. I wrote this with limited knowledge of bragi; by spitting through the rust sourcecode, mostly. I may have some edge-cases, or explanations wrong.
Hello, Sorry for the delay in addressing your work. It's really awesome! Did you use tools to generate the YAML document, or just painstaking hard work?
Personally Im not sure the generated HTML file adds much, and I agree it should be available, generated by the CI.
I am at work on having a 'project' website, which would include the documentation (including the generated interface) and a demo.
The YAML was written mostly by hand. I had to investigate all ins- and outs anyway.
Anything you need from me? Should I remove the HTML in this branch, for example?
I lean toward removing the generated HTML file in this branch, if you don't mind. If you are OK with that, perhaps you can remove it, and I can merge your PR.
Thank you Ber
I've removed the commit that introduced the html. We now only have the swagger yml file.
Maybe I should change the README to link to the swagger doc with an explanation? And then also rewrite the endpoints-table in that README a little so the TODOs can be removed?
btw https://github.com/wafflespeanut/paperclip could be useful here (even if for the moment openapi 3 is not yet supported)
AFAICS it is mostly tooling to generate a Rust client from an OpenAPI spec. It mentions that it can generate the spec from an actix-web setup, though. Did you try that, by any chance?
nop didn't try the spec generation (I needed openapi v3 for some other project, so I used a combination of openapi schema for the ouput and handcrafted code for the parameters) but it seems cool!