starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[PR #4972] [CLOSED] feat: Auto-generate OpenAPI documentation #4387

New Issue
Closed
opened 2026-04-25 00:19:33 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:19:33 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/4972
Author: @hypnotoad08
Created: 1/9/2026
Status: ❌ Closed

Base: master ← Head: master

📝 Commits (1)

  • 0694c2f Implement swagger-autogen for API documentation

📊 Changes

5 files changed (+7114 additions, -0 deletions)

View changed files

📝 docs/README.md (+9 -0)
➕ docs/swagger-output.json (+6874 -0)
➕ swagger.js (+118 -0)
➕ view-docs.js (+56 -0)
➕ view-swagger.js (+57 -0)

📄 Description

Brief summary

Adds an OpenAPI generation pipeline (extract/merge/verify + optional client check), expands optional route params into separate OpenAPI paths, and updates YAML specs for author image upload and podcast create request bodies.

Which issue is fixed?

API Docs are incomplete

In-depth Description

  • scripts/extract-openapi-with-schemas.js - Extracts routes and model schemas and expands optional params like :episodeId? into two paths.
  • scripts/merge-openapi-specs.js - Merges the hand-crafted OpenAPI spec (generated from YAML) with generated paths and schemas.
  • scripts/verify-code-vs-openapi.js - Compares the spec against controller usage.
  • scripts/verify-client-vs-openapi.js - Checks client API calls against the spec.
  • swagger-docs.js / view-docs.js - Local Swagger UI and ReDoc viewers for docs/openapi-generated.json.
  • YAML updates in docs/controllers/AuthorController.yaml, docs/controllers/PodcastController.yaml, and docs/objects/mediaTypes/Podcast.yaml.
  • Generated output in docs/openapi-generated.json.

Pipeline and doc viewers are run manually.

How have you tested this?

  • npx @redocly/cli bundle root.yaml -o openapi.json (from docs/)
  • node scripts/run-documentation-pipeline.js (165 paths, 116 schemas, 100% coverage)
  • node scripts/verify-client-vs-openapi.js (231 client endpoints scanned, 0 missing)
  • Doc viewers were run manually as needed (node swagger-docs.js, node view-docs.js).

Screenshots

N/A

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/advplyr/audiobookshelf/pull/4972 **Author:** [@hypnotoad08](https://github.com/hypnotoad08) **Created:** 1/9/2026 **Status:** ❌ Closed **Base:** `master` ← **Head:** `master` --- ### 📝 Commits (1) - [`0694c2f`](https://github.com/advplyr/audiobookshelf/commit/0694c2fb1c87f590264e5044e2dd16cd4c5c2e8e) Implement swagger-autogen for API documentation ### 📊 Changes **5 files changed** (+7114 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/README.md` (+9 -0) ➕ `docs/swagger-output.json` (+6874 -0) ➕ `swagger.js` (+118 -0) ➕ `view-docs.js` (+56 -0) ➕ `view-swagger.js` (+57 -0) </details> ### 📄 Description <!-- For Work In Progress Pull Requests, please use the Draft PR feature, see https://github.blog/2019-02-14-introducing-draft-pull-requests/ for further details. If you do not follow this template, the PR may be closed without review. Please ensure all checks pass. If you are a new contributor, the workflows will need to be manually approved before they run. --> ## Brief summary Adds an OpenAPI generation pipeline (extract/merge/verify + optional client check), expands optional route params into separate OpenAPI paths, and updates YAML specs for author image upload and podcast create request bodies. ## Which issue is fixed? API Docs are incomplete ## In-depth Description - `scripts/extract-openapi-with-schemas.js` - Extracts routes and model schemas and expands optional params like `:episodeId?` into two paths. - `scripts/merge-openapi-specs.js` - Merges the hand-crafted OpenAPI spec (generated from YAML) with generated paths and schemas. - `scripts/verify-code-vs-openapi.js` - Compares the spec against controller usage. - `scripts/verify-client-vs-openapi.js` - Checks client API calls against the spec. - `swagger-docs.js` / `view-docs.js` - Local Swagger UI and ReDoc viewers for `docs/openapi-generated.json`. - YAML updates in `docs/controllers/AuthorController.yaml`, `docs/controllers/PodcastController.yaml`, and `docs/objects/mediaTypes/Podcast.yaml`. - Generated output in `docs/openapi-generated.json`. Pipeline and doc viewers are run manually. ## How have you tested this? - `npx @redocly/cli bundle root.yaml -o openapi.json` (from `docs/`) - `node scripts/run-documentation-pipeline.js` (165 paths, 116 schemas, 100% coverage) - `node scripts/verify-client-vs-openapi.js` (231 client endpoints scanned, 0 missing) - Doc viewers were run manually as needed (`node swagger-docs.js`, `node view-docs.js`). ## Screenshots N/A --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2026-04-25 00:19:33 +02:00
adam closed this issue 2026-04-25 00:19:33 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#4387
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?