Low budget developer portal
Published on 9 February 2023 by Andrew Owen (4 minutes)
Back in 2019, I had to create a developer portal with no budget. I wrote up the experience and last year I published it here as a three part series. My requirements were that it would have the tri-pane view, with contents, endpoints and code examples, that developers would be able to contribute to it, and that it would support diagrams. My solution was to create a Markdown-based static site with Swagger APIs rendered by ReDoc and diagrams provided by Mermaid. I must have been on to something because recently, Redocly had the same idea. It currently has a developer portal product in beta. If you want to check it out, the company is now running its own website on it. Now if you have no budget, you can still do it the way I suggested, but for US$3600 a year (at time of writing) there is an easier way that includes hosting.
Before I go on, I feel the need to point out that this isn’t paid product placement. I’ve been surprised to learn how widespread the practice is. Call me naive. I also ended up working for a company whose product I’ve previously advocated for on this blog. I like the product. That’s why I took the job. But if I do mention it again, I’ll declare my interest. I don’t need to monetize this blog, so it will never be ad-supported, either directly or indirectly. I just really like the free open source ReDoc tool and I think US$300 a month is a very reasonable ask for a dev portal solution.
So, what do you get for your money:
Back in the days of my no-budget dev portal, I was always asking for support from a front end developer to improve the look and feel. I never got one, because they were always busy with other things. According to Glassdoor, the average annual salary of a front end developer is US$84,250 a year. So far as I’m concerned, any tool that delivers good-looking, accessible customer facing content that costs less than that’s probably a good deal.
Swagger, OpenAPI and static sites (as supported by static site generators such as Hugo) enable documentation to be written in Markdown. This is important, because typically developers hate writing anything (especially code comments). So if you can get them to write, you want to make it as easy as possible for them. And those that do write seem comfortable using Markdown.
API schemas are great. But API documents on their own don’t provide all the information a developer needs to know how to use an API. Before I hit an endpoint, maybe I need to hit some other endpoints first to set up some data. This is where workflows are really useful, and why I added Mermaid support to my developer portal. Mermaid enables you to create diagrams from Markdown. Which means you don’t have to maintain separate image files, and the diagrams can be edited in a code editor.
With a static site generator, you have to configure your own page templates. Redocly gives you templates for tutorials and guides, contextual docs, landing pages, examples, multiple APIs and code samples. With my no-budget solution, you have to manage your own automation for getting the API docs into the portal. Redocly connects directly to your Git repo (on the major hosted Git platforms). And the portal is automatically rebuilt when the API registry updates.
I don’t know exactly what framework Redocly is using, but I suspect it’s an off-the-shelf static site generator with customizations. As well as Markdown, it supports MDX. And configuration is done in YAML and TypeScript. React components can be embedded in the Markdown. If I had to guess, I’d say it’s either Next.js, Gatsby or Docusaurus. It has the usual search engine optimization (SEO) stuff and analytics integrations. If someone asked me for a recommendation to get a developer portal up and running as quickly as possible, but be able to scale to meet demand, this would be it.