Forem has set a milestone to update our (v1) API documentation and we need YOUR help!
There are several endpoints that we would like to document i...
For further actions, you may consider blocking this person and/or reporting abuse
Are you interested in generating OpenAPI directly from your test cases? Hereβs a post about doing exactly this for Mastodon:
dev.to/appmap/automatically-genera...
It uses your regular test suite - you donβt have to rewrite or rearrange tests like you do with RSwag.
Ooooh this looks interesting - thanks for dropping it here @kgilpin, I'll give it a read π.
Hey, I just wanted to let you know that we've prepared a PR showing how to generate OpenAPI for Forem with AppMap - github.com/forem/forem/pull/19041
In the PR description you'll find information about how it works, and some instances of how the generated OpenAPI can enhance the definitions that are already in the Forem repo.
Using OpenAI is a great tool to see how we can play with datas. Such a good idea! Can't wait when the version is released to updating some projects like
thomasbnt / devtoprofile
An example of getting data from the dev.to API to display its own articles.
Getting data from the API of DEV.TO
An example of getting data from the dev.to API to display its own articles. Work with VueJS, fetch and the API v0 of dev.to (this version will be DEPRECIATED. See the post on DEV).
How to get my data ?
Change this lines in the file src/components/devto.vue :
How to get my ID ?
Get your ID by using the website. Press F12, and on the
body
element, you have adata-user
attribute. This is your ID.How to develop this project
Project setup
Compiles and hot-reloads for development
Compiles and minifies for production
Lints and fixes files
Customize configuration
See Configuration Reference.
Us too! π₯
This is a great and very thorough article. I'm def interested in contributing. Thanks for sharing.
A couple things to clarify: Swagger has been renamed as OpenAPI since 2015. Any reference to the specification should use OpenAPI. Swagger remains many products offered by SmartBear. Unfortunately, many tools in the ecosystem used the swagger moniker in their package names and haven't been updated. I see you tried to explain it but the terms should not be used interchangeably.
smartbear.com/blog/what-is-the-dif...
Secondly, now would be a great time to move to OAS3.1.x to take advantage of the full JSON Schema support. This allows usage of many of JSON Schema's features from draft 2020-12 and beyond, without limitation. Whereas OAS 3.0.x has quite a few limitations to design proper JSON Schemas. Not to mention it's based on a modified draft-04 version which is quite old.
Yup, I came to comment the exact same thing - should be starting from OAS rather than Swagger / aka βOAS pre-OASβ π happy to help with some of this work, so Iβll go ahead and talk a look at the related GitHub issue!
Thanks @andypiper. I went ahead an updated the article to make it a bit more clear and removed the confusing references where appropriate to the previous name (Swagger).
We're looking forward to your contribution β¨
Hi @jeremyfiel ππ½ Thanks so much for bringing that to my attention, I went ahead an updated the article to make it a bit more clear and removed the confusing references where appropriate to the previous name (Swagger).
That's a really good point, I'll bring it up to the team, we'll chat more about it and what it entails. Hopefully, we can upgrade soon!
Thanks again, we're looking forward to your contribution β¨
Interesting read and interesting approach to API documenting Ridhwana, thanks π
Talking about the OAS file you mentioned in the post, for me it was really interesting to audit it with 42Crunch audit tool (I work there but I'm a UI developer and not selling it just in case, full disclosure π and it's free anyway). If you check out the API docs with it (either through UI or using the VS Code plugin), you may find that first, the audit is blocked by a structural JSON issue (schema error):
and second, if you fix that quickly, there are some issues of different criticality which would be not very hard to fix, provided with the decent remediation instructions:
Again, I'm not a dev advocate of any kind, I just personally use the tool for my pet project and it helps me a lot, as I'm not a BE dev. And I truly wish Forem to become better and better, being a contributer myself for a couple of times π
@ridhwana have you thought about adding SDKs for the Forem API? It could help let with usability and integration speed. For some ideas, check otu the Forem SDKs I created in Go, Python, TS, and Typescript from your OpenAPI spec.
If you're interested, I could help you set up automation so that every time a new version of your OpenAPI spec is published, a new version of the SDKs are published. Let me know! Really admire the work you and the forem team do.