Refactor(docs/): complete migration to `docusaurus` for API documentation.

[KemingHe]

Current landing page https://api.osu.dev is generated by Swagger API, with following inconveniences:

1. Low customize-ability unless hard-code (current solution).
2. Doesn't look good and is NOT mobile-friendly (low priority).
3. Cannot be expanded or versioned (doc versioning, not git).

Let's plan for a full refactor.

[genesis-writing]

Hi @KemingHe I would like to help with this.

Are you looking to perhaps gradually build out the site for the API? I mean creating a home page, getting start guide, in addition to just housing the API spec.

Edit: typo

[KemingHe]

Hello @genesis-writing , grateful for your interest to contribute.

Are you looking to perhaps gradually build out the site fir the API?

Yes. The RESTful API is versioned (/v1/...); and it's a perfect match for Docusaurus's versioning feature. Instead of release versions, we will write API versions. Before we start, let me know what you think?

I mean creating a home page, getting start guide, in addition to just housing the API spec.

Love your enthusiasm and professionalism. This particular project is designed to be lightweight. Thus, we are just looking for:

• Landing/info page x1 at https://api.osu.dev
• API doc page x1 per api version (currently only v1) at https://api.osu.dev/v1

Here are the expectations:

1. Explore https://editor.swagger.io/ and the OpenAPI 3.0 standard.
2. Copy and paste current ./docs/openapi.yaml content into the Swagger Editor.
3. The Swagger Editor preview contains all the content needed for the documentation.
4. Full creative freedom. Create a ./docusaurus dir and please do share your plans here before you start.
5. Hear from you soon. ☀️

Edit: typo

[KemingHe]

Oh, and @genesis-writing , the standard dev workflow here:

1. Fork the repo.
2. Clone it and create your own branch git switch -c docs-docusaurus-genesis.
3. Make sure you use command line when committing, we use commitizen and release-it for conventional commit messages and changelog. Feel free to Google and ask about these tools here. (I'll be updating the contrib readme this weekend.)
4. Push your commits to your fork and create a PR to the origin main. I'll review it.

Edit: context

[genesis-writing]

Hi @KemingHe , thanks for assigning the issue to me. I'm looking forward to working with you :)

Versioning

Since we'll be working with API versions I think it's fair to use Docusaurus's versioning feature. This will allow the API to evolve and ensure we continue to support users who may be using different versions.

Site Contents

Ok sounds good. So the structure of the site will be as follows:

• Homepage: Based on the contents in https://api.osu.dev/
• Endpoints: Based on the contents in https://api.osu.dev/v1

Since the API 's version is 1.0.0, we'll start versioning the docs now so we lay the groundwork for the future. Down the line we can consider adding a changelog to communicate changes that may affect users moving from 1.0.0 to the new version.

Expectations

Thanks for the organized list. I'll take a look at the spec and start working on a gameplan for you to review before we move forward.

[KemingHe]

@genesis-writing Great!

Thanks for the organized list. I'll take a look at the spec and start working on a gameplan for you to review before we move forward.

On top of everything communicated earlier, here's the greater architecture (also will be updated into the main README.md this weekend):

• Documentation is hosted via Cloudflare Pages.
• Endpoints are individual Cloudflare Workders.
• No GitHub Action for deployment yet, as I'm deploying it via Cloudflare's Wrangler CLI.

Let me know if you have any questions, especially working with Swagger Editor and the ./doc/openapi.yaml.

I totally agree with you on making the documentation future-proof such that when we later add features to the existing endpoints, i.e. query parameters like /v1/undergrad-majors?filters=..., we can easily update the Docusaurus page(s).

Looking forward to your gameplan!! 🌻

[genesis-writing]

Hi @KemingHe thanks for sharing the architecture. Ok so in this case you'd like for me to make sure everything works locally and you will handle the deploy later? Hope I understood that correctly.

Proposed plugin

As far as the pending doc work goes, I looked at the docusaurus-openapi-docs plugin and I think this may be the way to go for the API. It's pretty cool because it also supports versioning, specifically for APIs. It will automatically create a dropdown version selector and add a version badge/breadcrumb for easy identification. It's a lightweight alternative to Docusaurus's versioning feature.

Demo

If you want to see the plugin in action check out the Petstore API site demo. You can see two different versions on the site. It also looks good on mobile.

Language Tabs

If you check out any of the endpoint demos (example) you can see that it comes with code snippets. There are 18 languages that are supported. The only one I couldn't find from the current doc website is Android but everything else is there.

Organization

If we go with this plugin we can organize the endpoints into their own sections and group the request methods underneath them. I think this would work well if there are plans to add to the existing endpoints as you mentioned earlier. You can see the Petstore demo does something similar by separating pets, petstore orders, and users.

Let me know what you think! 😎

[KemingHe]

@genesis-writing Wonderful research work!

Q&A

Ok so in this case you'd like for me to make sure everything works locally and you will handle the deploy later? Hope I understood that correctly.

Yes. For this task, we are only concerned about the ./docusaurus dir, and being able to (on your end) "run locally". Normally, no changes nor additions to the rest of the code base, but I'm open to suggestions.

docusaurus-openapi-docs plugin and demo

This is perfect: it drastically reduces your workload as well as standardizes it for the whole team. I read through the official docs and tried the demo. All looks great!! Bravo for doing the research.

Android is not supported?

I see that Kotlin (modern Android dev language) is supported, so we should be fine. Don't worry about matching 1-to-1 the languages. I trust the plugin devs can deliver the best practices on this part.

If we go with this plugin we can organize the endpoints into their own sections and group the request methods underneath them. I think this would work well if there are plans to add to the existing endpoints as you mentioned earlier. You can see the Petstore demo does something similar by separating pets, petstore orders, and users.

Yes. I love the demo organization.

Further Help Needed

Hmmm, I don't want the api doc site to conflict with the actual api. The versioned groups could be https://api.osu.dev/docs/v1/something? (very open to new suggestions)

(Running locally, it will look like localhost:xxxx/... instead of https://docs.api.osu.dev/....)

Core principle: let's make as few changes to the auto-generated output as possible, to streamline workflow for now and future.

Branding and Credits

At the end of the development, we will add the appropriate organization logo, branding, contact info. etc. Don't worry about them for now. Promise no big styling changes, adhering to the core principle.

Also as final touches, you are more than welcome to create a credits page for all contributors, included could be your personal section with photo, links, and bio (full creative freedom on how it looks). Remember to make this modular so that I and future contributors can easily use it for ourselves, too.

Content Breakdown

• Landing page + one intro page per version OR default redirects to latest version intro page?
• One group of pages per endpoint, as shown in the demo
• Credits page

Looking forward to seeing your experiments on your own branch. Amazing work so far! 👏🏼

Edit: new architecture decisions (next comment) voids certain former concerns.

[KemingHe]

Hi @genesis-writing , I got some feedback from my mentor on best practices. Here are the good news that will make this task even more streamlined:

• API endpoints will stay at https://api.osu.dev domain.
• Documentation will be at new https://docs.api.osu.dev domain.

Don't worry about documentation site routing and stuff, the api and doc sites are completely separate. And again adhering to the core principle earlier, make as few changes as possible to the auto-generated site based on our existing ./docs/openapi.yaml.

Happy to make everyone's lives easier here, plus following industry best practice.

[genesis-writing]

Woohoo! Thank you. I appreciate you taking the time to read and answer everything @KemingHe . Exciting times ahead :) and yes, I think less is more with this refactor, especially as the project scales in the future.

So long story short:

• Phase 1: meet your original requirements, no styling
• Phase 2: add final touches

Hope you have a nice weekend 🤠