DEV Community

Documenting Forem's v1 API

Ridhwana Khan on January 19, 2023

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...
Collapse
 
kgilpin profile image
Kevin Gilpin • Edited

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.

Collapse
 
ridhwana profile image
Ridhwana Khan

Ooooh this looks interesting - thanks for dropping it here @kgilpin, I'll give it a read πŸ‘€.

Collapse
 
kgilpin profile image
Kevin Gilpin

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.

Collapse
 
thomasbnt profile image
Thomas Bnt β˜•

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

GitHub logo thomasbnt / devtoprofile

An example of getting data from the dev.to API to display its own articles.

Made with VueJS GitHub last commit Depfu Discord GitHub Sponsors Twitter Follow

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).

Note

See the preview of this project here β†’

Preview of this project

Note

More projects like that ? Check this list.

See the list of awesome projects with an API

How to get my data ?

Change this lines in the file src/components/devto.vue :

const USERID_DEVTO = '18254'
const USERNAME_DEVTO = 'thomasbnt'
Enter fullscreen mode Exit fullscreen mode

How to get my ID ?

Get your ID by using the website. Press F12, and on the body element, you have a data-user attribute. This is your ID.

How to get my dev.to ID


How to develop this project

Project setup

yarn install
Enter fullscreen mode Exit fullscreen mode

Compiles and hot-reloads for development

yarn serve
Enter fullscreen mode Exit fullscreen mode

Compiles and minifies for production

yarn build
Enter fullscreen mode Exit fullscreen mode

Lints and fixes files

yarn lint
Enter fullscreen mode Exit fullscreen mode

Customize configuration

See Configuration Reference.




Collapse
 
ridhwana profile image
Ridhwana Khan

Us too! πŸ”₯

Collapse
 
jeremyfiel profile image
Jeremy Fiel

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.

Collapse
 
andypiper profile image
Andy Piper

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!

Collapse
 
ridhwana profile image
Ridhwana Khan

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 ✨

Collapse
 
ridhwana profile image
Ridhwana Khan

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).

Secondly, now would be a great time to move to OAS3.1.x to take advantage of the full JSON Schema support.

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 ✨

Collapse
 
fyodorio profile image
Fyodor

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):

Image description

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:

Image description

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 πŸ˜…

Collapse
 
ndimares profile image
Nolan Di Mare Sullivan

@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.