Migration from apidoc to swagger / openapi as documentation backend.

[ByteZent]

General Info

• UUID: f0c0dd64-8826-4848-a9ca-e770f4ecd17a

Description

While getting familiar with the project and the API, I discovered that the current version of the API documentation was generated using apidoc. Unfortunately, this tool is no longer actively maintained, meaning no further updates will be provided unless a new maintainer takes over.

To explore the different parts of the API and get a better sense of its structure, I spent some time integrating Swagger UI with Swagger JSDoc into the project to test its compatibility with Express.

I'd like to discuss the possibility of migrating from apidoc to Swagger as the new API documentation backend. Here are a few reasons why I believe this would be beneficial:

1. Swagger/OpenAPI is the industry standard for API documentation, widely recognized and understood by developers across various platforms.
2. The Swagger ecosystem is actively maintained and continuously improved, offering ongoing updates and new features.
3. With Swagger, I can execute API requests directly from the documentation UI, providing an easier and more efficient testing environment during development and prototyping.

I’d be happy to explore this transition further and discuss any questions or concerns.

Example - Current Version of Api Doc for WorldState

WIP - Documentation for WorldState with Swagger integration

Code - Documentation for Endpoint as comment in world.js

 * @swagger
 * /api/v4/world-state:
 *   get:
 *     produces:
 *       - application/json
 *     description: Does not require authentication
 *     summary: Get the state for the game world
 *     operationId: WorldStateGet
 *     responses:
 *       200:
 *         description: A successful response
 *         content:
 *            application/json:
 *              schema:
 *                type: object
 *                properties:
 *                  npcImageSuffix:
 *                    type: string
 *                    description: Trailing component of NPC image filenames
 *                    example: _fall

By adding Swagger documentation on a new route, we can migrate the API endpoint by endpoint, allowing for a gradual and seamless transition.

I’d love to hear the team’s thoughts on this, as I see it as a quality-of-life improvement for developers working with the API.