ShowDoc review: self-hosted API and technical documentation for IT teams

The problem ShowDoc targets: documentation that lives in someone's IM history

The README opens with a scenario most backend engineers recognize: you take over a module written by someone else, and the code has no notes. The documentation exists somewhere, but asking around for it and waiting for a copy over IM or email is the actual workflow in many teams. ShowDoc's answer is to put the document behind a URL so the latest version is the one people open.

The audience is narrow and clear. It is an IT team, not a product team, and the three document types the README names are API documents, data dictionaries and explanation documents such as tool instructions or technical specifications. If your team writes user-facing help centers or marketing pages, nothing in this project is aimed at you. The pitch is internal reference material that stays current because editing and reading happen in the same place.

How the PHP application is put together

The repository is a PHP application with a conventional split. index.php sits at the repository root, Public/, server/ and web/ hold the application code, and web_src/ holds front-end sources. The Sqlite/ directory is present at the top level, which tells you the default storage is SQLite rather than an external database server. That choice is what makes a single-container deployment realistic: there is no separate database service in docker-compose.yml, just the showdoc service.

The compose file mounts two volumes. ./showdocdata/html is mapped to /var/www/html, and /showdoc_data is mapped to /showdoc_data_old, which the comment describes as compatibility with historical version files. The service listens on port 4999 on the host and forwards to port 80 in the container. restart: always is set, so the container comes back after a reboot without supervision.

The Dockerfile builds from webdevops/php-nginx:8.3-alpine by default, which covers amd64 and arm64. For 32-bit ARM such as arm/v7, the documented path is to inject an older base image with BASE_IMAGE=wordpress:php8.1. That fallback branch does something worth knowing about: it copies the code into /var/www/html, removes the anydoc binary, writes a PHP entry point that renders web/index.html, and then runs chmod -R 777 on the web root. A world-writable web root is a real trade-off accepted for compatibility with older platforms, and you should treat it as such rather than as a neutral detail.

Installing ShowDoc with Docker and writing a first API page

The README points self-hosters at documentation/en/AutoInstall.md for deployment steps and at docker-compose.yml for the container definition. The compose file already carries the image name and port mapping, so the shortest path is to start the stack from the repository root.

docker compose up -d

After the container starts, the service is reachable at http://localhost:4999 because the compose file maps 4999 on the host to 80 inside the container. The first page you see is the ShowDoc web interface; the README does not document the default credentials, so set them during your own install rather than assuming a value.

If you are building the image yourself rather than pulling it, the compose file documents a build argument for users in China:

docker compose build --build-arg IN_CHINA=true

For 32-bit ARM platforms the documented invocation sets both a base image and the China flag:

docker build --build-arg BASE_IMAGE=wordpress:php8.1 \
             --build-arg IN_CHINA=true .

Once you are logged in, create a project and open a page. The editing page has a button at the top that inserts an API interface template or a data dictionary template. The README describes the intent plainly: after inserting a template you only fill in the data. That is the fastest way to see whether the Markdown editor suits your team, and it avoids hand-writing the same field table for every endpoint.

The hardening step the README calls mandatory

The deployment section of the README contains one line that should decide your rollout order. Self-hosted Nginx and Apache users must deny access to the Sqlite/ directory to prevent RCE, and the README links to documentation/zh-CN/Security.md. That document is in Chinese only, which is itself a friction point for an English-speaking team: the instruction is clear enough to act on, but the reasoning behind it is not available in the English documentation set.

The practical reading is that the directory holding SQLite data files must not be reachable over HTTP. If you put ShowDoc behind Nginx or Apache without that rule, you have left a writable data directory under the web root. The Docker path is not automatically exempt: the compose file mounts ./showdocdata/html into /var/www/html, so the same directory tree is served by the container's web server. Anyone exposing port 4999 to the internet should treat the deny rule as part of the install, not as a follow-up task. The README also ships a SECURITY.md at the repository root for reporting issues, which is where a vulnerability should go rather than into a public issue.

Permissions, version history and what the README leaves unsaid

Projects are either public or private. Public projects are viewable by anyone; private projects require a login, with the password set by the project owner. Members can be added and removed, and members can edit documents, but only the owner can transfer or delete a project. That last restriction is a sensible default for a tool where a careless delete would take a team's API reference with it.

Version history exists per page, and the README says you can restore a previous version. What it does not document is rollback at the project level, or what happens to history when a project is transferred. Export is described as producing an offline Word document for a project, which is useful for handover but not a backup format you would want to rely on for restore. The README is silent on backup procedure for the SQLite data itself, so plan the volume copy yourself.

The editing model is Markdown with templates. There is no mention of a generated client, an OpenAPI import, or automated test hooks against the documented endpoints. Teams used to writing a spec once and generating mocks and clients from it will find ShowDoc is a document store, not a schema compiler. The repository does contain mock/ and mcp.php at the top level, but the README does not explain either, so do not plan around them based on the file names alone.

ShowDoc compared with a spec-first tool such as Apifox

The nearest alternative people search for alongside ShowDoc is Apifox, and the difference is in where the source of truth lives. Apifox is built around a structured API definition that drives documentation, mocking and testing from one model. ShowDoc is built around pages: you write Markdown, insert a template, and the document is the artifact. There is no requirement that the page match a machine-readable schema, and no promise that changing the page changes anything else.

That makes ShowDoc easier to adopt for a team that already has prose-heavy internal docs and wants them in one place with permissions and history. It makes it a poor fit for a team whose main pain is keeping request and response schemas synchronized across a mock server, a test suite and published docs. In that case the manual template insertion ShowDoc offers is the work you were trying to eliminate. The honest framing is that these are different categories: a documentation site with an editor versus an API lifecycle tool with a document view.

Licence, upgrade cost and the copyright notice

The README states ShowDoc is released under the Apache 2.0 Open Source License, and the repository ships LICENSE.txt. It then adds a condition that Apache 2.0 alone would not impose: the author star7th and the official site hold copyright and related rights, the program may be used or further developed free of charge provided the copyright information and links on the program UI are retained, and changing that copyright information or those links requires official consent and authorization. The repository metadata reports the licence as NOASSERTION, which is consistent with a licence file that carries an extra notice rather than plain Apache 2.0. If you plan to white-label the interface, read LICENSE.txt and the README's copyright section before you start, and take legal advice rather than treating this summary as one.

Upgrade cost is tied to the container. Releases are frequent: v3.9.2 on 2026-07-27, v3.9.3 on 2026-09-02, v3.9.4 on 2026-09-04, and the last push to the repository was on 2026-09-16. The compose file pins image: star7th/showdoc:latest, which means a docker compose pull followed by docker compose up -d moves you to whatever is current. That is convenient and also the risk: there is no version pin in the file as shipped, so a rebuild can change the running version without a deliberate decision. The Dockerfile sets ENV SHOWDOC_DOCKER_VERSION=3.4.2, a value that does not track the release tags, so do not read it as the installed version. The volume layout includes the /showdoc_data to /showdoc_data_old mapping specifically for historical files, which suggests upgrades across older versions were a real concern. Back up the ./showdocdata/html volume before pulling.

Editorial conclusion

ShowDoc fits a small IT team that wants an internal Markdown wiki for API documents and data dictionaries, and is willing to run the Docker image on its own server. It does not fit a team that needs a hosted SaaS with zero maintenance, or one that will expose the container to the internet without denying access to the Sqlite/ directory first. Before adopting it, read documentation/en/AutoInstall.md and documentation/zh-CN/Security.md, confirm the volume path ./showdocdata/html is writable, and check whether the Apache 2.0 extra copyright notice is acceptable for your fork.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. star7th/showdoc on GitHub