Writing the Map While Building the City: A Week on MiseOS API Documentation

MiseOS Development - This article is part of a series.

Part 10: This Article

This week I focused on API documentation for the project.

I did not build a big new feature.
Instead, I documented what I already built — and that gave me a much better overview of the system.

What I worked on this week
#

I went through the API resource by resource and updated the documentation so it matches the actual codebase.

I documented and aligned:

Authentication
Users
Stations
Allergens
Dish Suggestions
Dishes
Weekly Menus
Ingredient Requests
Shopping Lists
Notifications
Menu Inspirations

I used the same structure in each doc:

short intro/context
endpoint overview table
request/response examples
auth roles
common error cases

How I documented it (tools)
#

I wrote the documentation in Markdown inside my Hugo portfolio, using one index page and one page per API resource.

Tools used this week:

Markdown + Hugo for publishing and navigation
IntelliJ HTTP Client for endpoint verification while documenting
Mermaid diagrams for workflow/state visuals
Live code cross-checking directly in the Java codebase (controllers, services, DTOs, mappers)

The goal was to produce manually curated docs aligned tightly with the implemented behavior.

How I structured the documentation
#

I created one API index page and separate pages for each resource.

The index page works like a table of contents, so it is easy to navigate the docs quickly.
From there, each resource has its own focused page with endpoints and examples.

This structure helped me keep things clean:

one place to get overview (index)
one place per domain/resource (detail pages)

It also makes it easier to maintain later, because changes are isolated to the relevant resource page.

Why this was useful (concrete aha)
#

Writing documentation was not just “text work”. It forced me to walk through the system as if I were a new developer consuming the API.

It helped me:

find small non-critical issues
catch unclear endpoint naming
spot inconsistencies in a few response examples
rethink parts of the API structure

The biggest aha came from the Weekly Menu response structure.

While documenting examples, I noticed menu slots did not always appear in a stable Monday → Friday order.
The reason was that slots came from an unordered collection returned by the persistence layer, so response order could vary.

That pushed me to make ordering explicit in the mapper:

sort first by day of week (MONDAY ... FRIDAY)
then by station id for deterministic ordering within the same day

This made the API output stable and predictable for frontend use and documentation examples.

Example from the mapper
#

List<WeeklyMenuSlotDTO> slots = menu.getWeeklyMenuSlots()
    .stream()
    .sorted(Comparator
        .comparingInt((WeeklyMenuSlot slot) -> sortByDayOrder(slot.getDayOfWeek().name()))
        .thenComparingLong(slot -> slot.getStation().getId()))
    .map(WeeklyMenuMapper::toSlotDTO)
    .collect(Collectors.toList());

And the day-order function:

private static int sortByDayOrder(String day) {
    return switch (day)
    {
        case "MONDAY" -> 1;
        case "TUESDAY" -> 2;
        case "WEDNESDAY" -> 3;
        case "THURSDAY" -> 4;
        case "FRIDAY" -> 5;
        default -> 99;
    };
}

In other words: writing docs exposed a real API usability issue, and fixing it improved both developer experience and UI reliability.

Diagrams helped more than expected
#

I added lifecycle/workflow diagrams in places where state matters (for example shopping lists and menu flow).

That helped both:

readers, because process and transitions are easier to understand quickly
myself, because drawing the flow made it obvious, if the API matched, what I actually wanted

If the diagram felt confusing, it usually meant the API behavior needed clarification too.

Highlights from this week
#

Weekly Menus
#

I clarified:

draft vs published behavior
role-based visibility (ANYONE vs management roles)
slot operations
publish constraints

Notifications
#

I aligned docs with real-time behavior:

WebSocket endpoint/auth expectations
broadcast vs user-targeted notifications
snapshot endpoint for badge/bootstrap use cases
no offline queue (fire-and-forget)

Menu Inspirations
#

I documented both modes:

GET /menu-inspirations/daily
SSE /menu-inspirations/stream

Including event types:

status
dish
done
error

Shopping Lists
#

I documented end-to-end flow:

generation from approved requests
AI normalization + fallback behavior
draft/finalized constraints
item operations + ordering endpoints
finalize precondition (all ordered)

What was difficult
#

The hardest part was choosing the right level of detail.

If docs are too short, they are not useful.
If they are too long, they are hard to read.

I tried to keep a practical middle ground for a school project: clear enough for someone to use and test the API, but still concise.

What I learned
#

Good docs require checking code, not memory.
A consistent template saves time and improves quality.
Index + resource pages is a good structure for medium-sized APIs.
Diagrams are very useful for state-based endpoints.
Documentation can reveal real implementation issues early.

Final reflection: Week 10 and backend wrap-up
#

This week became more than documentation work.
It also worked as a final backend quality check before the project hand-in.

By documenting every endpoint and flow, I could confirm that the core backend is now in a stable delivery state:

authentication and role-based authorization
menu and suggestion workflows
ingredient and shopping list lifecycle
real-time notifications
deployment and API availability

Looking back at the backend as a whole, one of the most important design choices was keeping the system layered and maintaining a clear separation of concerns. Controllers focus on HTTP translation, services contain business logic, and the DAO layer isolates persistence through JPA/Hibernate. This structure made it easier to expand the system while keeping individual components focused.

Another lesson was the value of placing business rules inside the domain model. Operations such as approving suggestions or finalizing shopping lists are implemented directly on the entities, which helps keep the rules consistent and easier to reason about.

Overall, documenting the API forced me to revisit every part of the system from the perspective of someone consuming the backend. That process helped confirm that the architecture and workflows are coherent and ready to support further development.