Skip to content
Smörgåsbord
AI slop felt appropriate here

DocServe

Going the extra mile just for kicks
Project repo

Peter Schmitz 2025/4/5



DocServe is a RESTful web API with modular endpoints that support patient data management in a mock healthcare setting for illustrative and educational purposes. The service is intended to represent a modern, “production-ready” service that features functional auth, containerized data persistence, ORM-driven migrations, integrated observability with OpenTelemetry, and dynamically-generated OpenAPI-powered live endpoint documentation.



Quickstart Guide

DocServe is capable of generating and serving its own fully interactive Swagger docs for manual testing and exploration. For a fully interactive API doc session you need to:

  1. Install the service

  2. Execute the serve command, typically as cargo run serve

  3. Navigate to the Swagger UI as it appears in the console output from the check command; By default the UI is available at http://localhost:3000/v1/swagger-ui

About

In March, I connected with several industry professionals whose work I genuinely admire. The conversations that followed left me feeling inspired and encouraged to start sharing more about what I’ve been working on. The biggest problem was that all of the professional work I’ve been doing for the past 5+ years is closed source. How do you talk about what you’ve been doing without actually talking about what you’ve been doing?

I quickly resolved to deliver some OAS documentation for illustration. I could start with a design-first approach and write a static service contract via Google protocol buffer and run a protoc-gen-openapi compiler plugin to generate an OAS. I could even take it a step further by either importing the compiled OAS or writing an OAS directly in SwaggerHub and adding some mock response data. Both of these options are valid, but the static nature of the project wasn’t super appealing to me. I wanted something a little more exciting. In the end I decided to write a fully funtional web service that generates live API reference documentation for fully-featured documentation and testing.

I’ve been writing a lot of Rust lately, so it felt like the natural starting point for my tech stack. I’d never built a web API with this kind of scope and feature set, and honestly didn’t know a lot about what modern REST services involve. I had discovered the Axum web framework from a previous project, and have been meaning to explore the Tokio async runtime, but was pretty uncertain about anything else. Whether by divine providence or simple alignment in preferences, I came across rust-api.dev, a project focused on building web APIs in Rust. The project illustrates approaches that loosely align with the The Twelve-Factor App. The concepts are all vaguely familiar, but I was pleasantly surprised to see it all presented so consisely. Sandor’s project became an almost immediate winner for me because not only did the material use the components I was already considering, and introduced me to all sorts of fantastic illustrations of the new concepts I was exploring. To my delight, everything is clearly documented and all the components are free and open source with liberal licensing, giving me the freedom to explore without any overhead. Perfect. Now all I needed was a basic concept and a plan to glue it all together.

The functionality of the API itself takes a backseat in this project. I chose a healthcare theme because it sounded interesting. From there I developed some fictional requirements around patient data. The main objective here is less about the specific API endpoints and more about exploring “production-ready” service features and applying the documentation practices I use in my professional work. This module organizes the service documentation into tutorial, how-to, and explanatory articles, following the Diátxis framework. The API reference documentation is accessible by running the service itself. Ultimately, the service offers a simple template for exploring new topics and ideas.