Add OpenAPI docs

TL;DR

I propose to switch to OpenAPI (fka Swagger) for API documentation. I am willing to contribute to this effort, but we need to discuss if and how this should be pulled of before. I am aware of ajayyy/SponsorBlock#706.

Why switch?

I think the API and docs just grew as this project developed and there is nothing wrong with that. I think that a point is reached where a switch to OpenAPI would make sense. OpenAPI can not only provide the same information that the wiki page currently does, but also improve on it. There are also additional advantages to using this widely adopted standard that I will go into.

I am aware that there is an inofficial OpenAPI documentation as the result of ajayyy/SponsorBlock#706. But I think that this doesn’t really get us anywhere. Besides the fact that this OpenAPI doc is unofficial, it is also hard to find. I only came across them by accident and only after a while and after starting my on draft. Because of that I think in the current situation this existing OpenAPI doc it is almost as good as none.

Advantages

You can read about the advantages of OpenAPI on the official website, but here are the main advantages that I see in this case.

1. Better accessibility of the API
   • raw spec instead of wiki page
   • -> better accessible for machines
   • -> better accessible for people e.g. via Swagger UI
     • (even) nicer presentation than a wiki page
     • allows to play around with an explore the API
     • would allow for stuff that would be hard/tedious to squeeze into an wiki page (e.g. https://swagger.io/docs/specification/links/)
2. Better docs
   • less ambiguous than the current docs are, in some places
   • more consistency/less “doc duplication”
     • e.g. compare the “segments” data model returned by /skipSegments and /skipSegments/:sha256HashPrefix.
     • The wiki shows two different models. In reality both responses use the same model.
     • OpenAPI would just reuse the model in this case, reducing doc duplication and also preventing mistakes like this one.
   • simpler way to version the api, deprecate stuff, etc.
3. Code generation
   • generate API clients for different languages
   • generate server stubs for different languages
   • e.g. https://github.com/swagger-api/swagger-codegen
   • -> spend less time on boring boilerplate code and have more time for actual features
   • -> less work for other developers that want to interact with SponsorBlock

I think code generation might have the biggest impact. It might be able to replace the manually written API client code in the web extension. And third party developers might be able to just go ahead use the API instead of writing their own code doing the tedious ground work first. I’m not sure, if there is currently an generator suitable to the SponsorBlock server, but if not, there might be one in the future. It could also become handy if the server implementation is switched to a different language or reimplemented later on.

Options

In general there are two options on how the switch to OpenAPI could be done:

1. Maintain docs separately
   • Maintaining them completely separate is always possible. This would be the same kind of work, that currently happens in the wiki.
   • There are also solutions, that allow you to put OpenAPI doc into doc blocks inside the code. This allows you for example, to document each API endpoint right above the exact function that will handle the corresponding request. This makes it easier to keep the docs up to date and check them against what’s actually happening.
     • One doc block solution that I played with is https://github.com/readmeio/oas. It works completely transparently and doesn’t add any build dependency to the code itself, since it will just parse comments in the source code, completely independently from the build of the application
2. Use a framework
   • Frameworks for different languages are available. Many provide advantages like deducing API endpoints/parameters/data models/error codes from the actual code, completely removing the need to manually maintain this info. Some frameworks are also able to take care of some boilerplate code, providing you with already parsed request/response data and error handling.

---

I would like to contribute to this effort. As I said, I played around with a doc block based solution, and it worked just fine. I am not familiar with typescript, so I don’t see myself diving into OpenAPI frameworks that could be used for this project. I want to discuss which approach should be pursued (or none at all) before I put too much work into it.

[uniquestring]

skipSegment by hash differs slightly since it also returns the video hash

Yes. With ‘the “segments” data model’ I meant just the model for each segment. Of course /skipSegments/:sha256HashPrefix wraps this with a container object, but if you just look at the segment, they still differ:

{
   segment: float[], //[0, 15.23] start and end time in seconds
   UUID: string,
   category: string,
   videoDuration: float // Duration of video when submission occurred (to be used to determine when a submission is out of date)
}

vs.

{
   segment: float[], // [0, 15.23] start and end time in seconds
   UUID: string,
   category: string
}

---

I have looked into this but there doesn’t seem to be any adapters I could find for mediawiki, which is our current wiki system

Yeah and even if there was, I don’t think it would make sense to use. Personally, I think the API docs could just be separate. Not all data can be pressed into the same format. You wouldn’t document a whole project on a Swagger page, and maybe, the other way around, you shouldn’t try too hard putting all docs on a wiki page. I’ve seen a lot of other Software, where they have some kind of handbook, but just link to the OpenAPI definition/Swagger UI for their API. Nothing wrong with that if you ask me.

---

I think the default override is necessary since some (quite) old clients are using the old endpoint and specify no other parameters, but the repeating categories over JSON array might be better

If backwards compatibility is a concern, then sure, maybe some stuff should be left in for now. But it isn’t really practical to keep it like this forever. At some point the API will (and probably should) break. Third party projects can’t rely on APIs never changing anyways. With API versions and deprecations, there are the right tools to signify such changes

---

also parsing the JSON causes some complications, if you go up then you can see the try/catch for JSON syntax errors 😛

Yeah, sure. This only was an example. The point was, that you have to worry about less.

Btw. this is exactly what a dedicated framework would take care of. Like always presenting you with an ready to go Category[] array or returning the appropriate error to the caller, if none was provided. All without you needing to do any of that manually in the code.

---

Most of the stuff is generalized, some isn’t since it’s not seen anywhere else. I’m open to PRs and recommendations and have interacted with most of the server code at some point so I’m no stranger to it.

I think I’ll just have my shot at it and then we can take a look and discuss. It’ll be easier than just hypothetically discussing all of this.

[mchangrh]

borrowing from https://github.com/Podcastindex-org/docs-api, RapiDoc might be a way to have presentable docs without going full-on with swagger