[PR #4344] [MERGED] Update API Docs #6347

New Issue

OVERLORD · 2026-02-05T10:29:59+03:00

OVERLORD commented

2026-02-05 10:29:59 +03:00

📋 Pull Request Information

Original PR: https://github.com/BookStackApp/BookStack/pull/4344
Author: @devdot
Created: 6/26/2023
Status: ✅ Merged
Merged: 7/5/2023
Merged by: @ssddanbrown

Base: development ← Head: update-api-docs

📝 Commits (8)

e43d85b API Docs: Remove id from Tag in Response
e478707 API Docs: Add Missing Type in Response
ca2d2c9 API Docs: Add User Slugs to Example Responses
3a39f13 API Docs: Remove Dates from Tags in Example Responses
23ae332 API Docs: Sort a few example responses
ccfe38e API Docs: Add book_slug to Example Responses
174cd5a API Docs: Add Missing editor fields in Example Responses
d293171 API Docs: Add Missing Fields in Example Responses

📊 Changes

12 files changed (+101 additions, -72 deletions)

View changed files

📝 dev/api/responses/books-create.json (+3 -3)
📝 dev/api/responses/books-read.json (+8 -5)
📝 dev/api/responses/chapters-create.json (+5 -19)
📝 dev/api/responses/chapters-list.json (+4 -2)
📝 dev/api/responses/chapters-read.json (+15 -5)
📝 dev/api/responses/chapters-update.json (+3 -16)
📝 dev/api/responses/pages-create.json (+7 -3)
📝 dev/api/responses/pages-list.json (+12 -3)
📝 dev/api/responses/pages-read.json (+7 -3)
📝 dev/api/responses/pages-update.json (+7 -3)
📝 dev/api/responses/shelves-create.json (+3 -3)
📝 dev/api/responses/shelves-read.json (+27 -7)

📄 Description

I came across a few minor issues in the API documentation.

(1) In the example response for read shelf/book, the tags have id - but they do not have id just like at any other endpoint.

(2) In the example response for read book, the page within contents does not have a type - but a quick test on the demo shows that any object within contents has a type.

I also noticed some fields are missing in the example responses, e.g. pages have an editor field (and sometimes url) and users within entities also a slug besides name and id. I assume it's an unnecessary bloat of the example responses to add those?

_{🔄 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/BookStackApp/BookStack/pull/4344 **Author:** [@devdot](https://github.com/devdot) **Created:** 6/26/2023 **Status:** ✅ Merged **Merged:** 7/5/2023 **Merged by:** [@ssddanbrown](https://github.com/ssddanbrown) **Base:** `development` ← **Head:** `update-api-docs` --- ### 📝 Commits (8) - [`e43d85b`](https://github.com/BookStackApp/BookStack/commit/e43d85b8016df9214f45d820231eba642fec1d0f) API Docs: Remove id from Tag in Response - [`e478707`](https://github.com/BookStackApp/BookStack/commit/e47870794df04590d5f5122f0cef8c10d9a97f81) API Docs: Add Missing Type in Response - [`ca2d2c9`](https://github.com/BookStackApp/BookStack/commit/ca2d2c97d443588e0eaee312788700806c57ace3) API Docs: Add User Slugs to Example Responses - [`3a39f13`](https://github.com/BookStackApp/BookStack/commit/3a39f13420f8ff754d23743a199faff786650b51) API Docs: Remove Dates from Tags in Example Responses - [`23ae332`](https://github.com/BookStackApp/BookStack/commit/23ae332c1b226bc21bea9b23f38228a8267c4f88) API Docs: Sort a few example responses - [`ccfe38e`](https://github.com/BookStackApp/BookStack/commit/ccfe38e9637dcc6fb86b7a450ebc79aa81567cc7) API Docs: Add book_slug to Example Responses - [`174cd5a`](https://github.com/BookStackApp/BookStack/commit/174cd5a89343463d73707af5928a8ce97f4285ce) API Docs: Add Missing editor fields in Example Responses - [`d293171`](https://github.com/BookStackApp/BookStack/commit/d293171da2dce020298308b0f1a6f455966bb8bb) API Docs: Add Missing Fields in Example Responses ### 📊 Changes **12 files changed** (+101 additions, -72 deletions) <details> <summary>View changed files</summary> 📝 `dev/api/responses/books-create.json` (+3 -3) 📝 `dev/api/responses/books-read.json` (+8 -5) 📝 `dev/api/responses/chapters-create.json` (+5 -19) 📝 `dev/api/responses/chapters-list.json` (+4 -2) 📝 `dev/api/responses/chapters-read.json` (+15 -5) 📝 `dev/api/responses/chapters-update.json` (+3 -16) 📝 `dev/api/responses/pages-create.json` (+7 -3) 📝 `dev/api/responses/pages-list.json` (+12 -3) 📝 `dev/api/responses/pages-read.json` (+7 -3) 📝 `dev/api/responses/pages-update.json` (+7 -3) 📝 `dev/api/responses/shelves-create.json` (+3 -3) 📝 `dev/api/responses/shelves-read.json` (+27 -7) </details> ### 📄 Description I came across a few minor issues in the API documentation. (1) In the example response for read shelf/book, the tags have `id` - but they do not have `id` just like at any other endpoint. (2) In the example response for read book, the page within `contents` does not have a `type` - but a quick test on the demo shows that any object within `contents` has a `type`. I also noticed some fields are missing in the example responses, e.g. pages have an `editor` field (and sometimes `url`) and users within entities also a `slug` besides `name` and `id`. I assume it's an unnecessary bloat of the example responses to add those? --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

OVERLORD added the pull-request label 2026-02-05 10:29:59 +03:00

OVERLORD closed this issue

2026-02-05 10:30:00 +03:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#6347