DEV Community: Maxwell Smart

The Fastest Way to Document Your API Without Learning OpenAPI

Maxwell Smart — Tue, 24 Mar 2026 00:17:57 +0000

You built a useful API. You want to share it with your team, a client, or the internet.

Then you look at what it takes to create proper documentation and immediately want to close the laptop.

OpenAPI spec? YAML files? Swagger UI setup? Postman collections? For a 6-endpoint side project that took you a weekend to build, this is not a reasonable ask.

Here's the lightweight approach that actually gets documentation shipped.

Why API Documentation Is Always the Last Thing That Gets Done

The tooling was designed for teams with dedicated technical writers and DevOps engineers. For solo developers and small teams, the standard options look like this:

Swagger/OpenAPI: Powerful but requires learning a YAML specification format before you can write a single word of actual documentation. The learning curve is real.

Postman: Requires an account, a workspace, and importing your collection. Good for testing. Overkill for shareable docs.

ReadMe.io / GitBook: $50-200/month. Reasonable for a funded startup. Not for a side project.

A Google Doc: Actually works, but looks unprofessional and has zero structure for endpoint documentation.

The result: most API projects ship with either no documentation, a half-finished README, or a Notion page with a table that gets out of date immediately.

What API Documentation Actually Needs to Contain

Strip it down to what the reader actually needs:

Base URL â€” where do requests go?
Method + path â€” GET /users/{id}
What it does â€” one sentence
Auth requirements â€” bearer token? API key? Nothing?
Request parameters / body â€” what shape does the input take?
Response example â€” what does the output look like?
Status codes â€” what errors should I handle?

That's it. Everything else is extra. If your documentation covers those seven things for every endpoint, developers can integrate your API.

The Fastest Way to Ship API Docs

The key insight: you don't need a documentation platform. You need a documentation output â€” a URL you can share that renders your endpoints cleanly.

The workflow that works for side projects and small teams:

Open DocForge
Fill in your API name, base URL, and description
Add each endpoint â€” method, path, description, example request/response, auth type, status codes
Click "Generate Doc Link"
Share the URL

The generated link is a standalone documentation page â€” syntax-highlighted, mobile-responsive, professionally formatted. Recipients don't need an account. You don't need a subscription.

Free plan covers 3 endpoints. Pro ($9 one-time) unlocks unlimited.

When to Graduate to OpenAPI

Once your API has external consumers (paying customers or public users), it's worth investing in a proper OpenAPI spec. The spec unlocks:

Auto-generated SDKs
Interactive "try it" consoles
Integration with API gateways

Until that point, don't let the tooling get in the way of shipping the documentation. A shared link with clearly formatted endpoints is infinitely better than a README that says "docs coming soon."

Ship the docs when you ship the API. Use the lightest tool that gets it done.

How to Add Open Graph Images to Your Next.js Blog (Complete Guide)

Maxwell Smart — Tue, 24 Mar 2026 00:11:39 +0000

You launched your Next.js blog. It looks great in the browser.

Then someone shares a post on Twitter and it shows up as a blank card with no image, no title, just a raw URL. You get 4 clicks instead of 400.

Here's how to fix it in under 10 minutes â€” and make every post look professional when shared anywhere.

What Next.js Gives You Out of the Box

Next.js has excellent metadata support via the generateMetadata function (App Router) or Head component (Pages Router). But it only generates the tags â€” you still need to provide an actual image file for og:image.

Most tutorials skip this part. They show you how to add the tags but leave you to figure out where the image comes from.

The App Router Approach

In your app/blog/[slug]/page.tsx:

import type { Metadata } from 'next'

export async function generateMetadata({ params }): Promise<Metadata> {
  const post = await getPost(params.slug)

  return {
    title: post.title,
    description: post.excerpt,
    openGraph: {
      title: post.title,
      description: post.excerpt,
      images: [
        {
          url: `https://yourdomain.com/og/${params.slug}.png`,
          width: 1200,
          height: 630,
          alt: post.title,
        }
      ],
    },
    twitter: {
      card: 'summary_large_image',
      title: post.title,
      description: post.excerpt,
      images: [`https://yourdomain.com/og/${params.slug}.png`],
    },
  }
}

Pages Router Approach

In your blog post component:

import Head from 'next/head'

export default function BlogPost({ post }) {
  return (
    <>
      <Head>
        <meta property="og:title" content={post.title} />
        <meta property="og:description" content={post.excerpt} />
        <meta property="og:image" content={`https://yourdomain.com/og/${post.slug}.png`} />
        <meta property="og:type" content="article" />
        <meta name="twitter:card" content="summary_large_image" />
        <meta name="twitter:image" content={`https://yourdomain.com/og/${post.slug}.png`} />
      </Head>
      {/* post content */}
    </>
  )
}

The Part Everyone Skips: Creating the Images

Both approaches assume you have a 1200Ã—630 PNG at /public/og/[slug].png.

You have three options:

Option 1: Dynamic generation with @vercel/og
Generates images on the fly via Edge Runtime. Powerful but requires setup, and adds latency to every share.

Option 2: Manual Figma/Canva for each post
Works but doesn't scale. You'll stop doing it by post #5.

Option 3: Generate once per post with a browser tool
This is what most indie bloggers actually do. Open OGForge, type your post title, pick a template, download the PNG, drop it in /public/og/. Takes 30 seconds per post.

For personal blogs and small teams, Option 3 is the right call. No infrastructure, no build step, no maintenance.

Testing Your Tags

After deployment, test with:

opengraph.xyz â€” shows exactly what Twitter/LinkedIn will render
LinkedIn Post Inspector: linkedin.com/post-inspector
Twitter Card Validator: cards-dev.twitter.com/validator

One thing to watch: platforms cache OG data aggressively. If you update an image, use the validator tools to force a cache refresh before sharing.

The Checklist

Before publishing any Next.js blog post:

[ ] og:title set
[ ] og:description set (under 200 chars)
[ ] og:image set and pointing to a real 1200Ã—630 PNG
[ ] twitter:card set to summary_large_image
[ ] Image tested in opengraph.xyz

Your posts are already good. Stop letting a missing PNG be the reason nobody clicks them.

Why Verbal Agreements Are Costing Freelancers Thousands (And the Fix)

Maxwell Smart — Tue, 24 Mar 2026 00:09:45 +0000

A client asked for "just one small change" last Tuesday.

By Friday it had become a full redesign. No extra pay. No documentation. Just a Slack message that said "we discussed this" â€” which you have no way to prove or disprove.

This is how freelancers lose thousands every year. Not to bad clients, but to undocumented agreements.

The Real Cost of Verbal Agreements

Most freelancers underestimate what undocumented scope actually costs them:

Unpaid revision cycles: The average freelance project runs 2.3x over the original scope with no additional compensation (Bonsai, 2025)
Dispute resolution time: Freelancers spend an average of 4 hours per disputed project trying to reconstruct what was originally agreed
Relationship damage: Even when you win a scope dispute, you usually lose the client

The problem isn't malicious clients. Most clients genuinely forget what was agreed. They remember conversations differently than you do. Without a written record, you're both guessing.

What a Proper Scope Agreement Looks Like

A solid project scope document answers four questions:

What is being built? Specific deliverables, not vague descriptions
What is NOT included? The out-of-scope clause is the most important part most freelancers skip
What does "done" look like? Acceptance criteria prevent endless revision loops
When was this agreed? A timestamp that neither party can dispute

Most freelancers either skip this entirely or use a 10-page contract that clients ignore. Neither works.

The Lightweight Alternative

You don't need a lawyer or a contract template. You need a shared link that both parties have seen and confirmed.

The workflow that works:

Before any project kicks off, write down exactly what you're delivering â€” specific features, pages, deliverables
Write down what you're explicitly NOT delivering (this is the clause that saves you)
Send the client a link to review it
They click to confirm. You have a timestamped record of what was agreed.

That's it. No PDF attachments. No DocuSign. No back-and-forth on contract language.

ScopeGuard does exactly this â€” generates a shareable scope link in 60 seconds. Client clicks, reviews the deliverables and out-of-scope clause, confirms. You get a timestamped link you can reference in any future dispute.

What to Do Right Now

If you have an active project with no written scope:

Open a new scope doc right now â€” even mid-project
Write down what you've agreed to so far
Send it to the client for confirmation before doing another hour of work

One scope dispute costs more than the 60 seconds this takes to set up. Stop doing handshake deals. Start every project with a link.

Why Your Links Look Broken on Slack (And the 5-Minute Fix)

Maxwell Smart — Mon, 23 Mar 2026 23:30:08 +0000

You wrote a solid article. You hit publish. You share the link on Slack.

It shows up as a plain URL with no image, no title preview, just a bare link that nobody clicks.

That's an Open Graph problem. And it kills more traffic than bad headlines.

What Open Graph Actually Does

When you paste a URL into Twitter, LinkedIn, Slack, Discord, or iMessage, those platforms send a bot to scrape your page. The bot looks for specific <meta> tags in your <head> to build the preview card.

If those tags are missing or wrong, you get a blank card. Sometimes you get nothing at all.

The four tags that matter most:

<meta property="og:title" content="Your Title Here" />
<meta property="og:description" content="A short description." />
<meta property="og:image" content="https://yoursite.com/og-image.png" />
<meta name="twitter:card" content="summary_large_image" />

The og:image is the one most developers skip. It requires an actual image file â€” 1200Ã—630px, hosted somewhere public, referenced by URL. Most people either ignore it or spend 20 minutes in Figma making something mediocre.

Why the Image Matters More Than You Think

Studies consistently show that social posts with images get 2â€“3Ã— more clicks than text-only posts. For developers sharing articles, tools, or projects, a good OG image is the difference between 12 clicks and 400.

The image is also the first thing people see. Before they read your title, before they decide to click, they see your image. A blank gray square tells them nothing. A bold, branded 1200Ã—630 image tells them you give a damn.

The Problem with Existing Approaches

Most developers fall into one of three traps:

Trap 1: Skip it entirely. The link looks broken. Traffic suffers.

Trap 2: Use a static screenshot. Doesn't match your brand, looks lazy, can't be updated without going back into Figma.

Trap 3: Set up a headless browser image generation service. Puppeteer, a serverless function, environment variables, 3 hours of your life gone. Completely overkill for a blog or side project.

There's a better path.

Generate OG Images in 30 Seconds

I've been using OGForge â€” a free browser-based tool that lets you build a proper 1200Ã—630 OG image with zero setup.

You type your title, subtitle, author name, and tag. Pick a template (there are 12 â€” from clean minimal to neon to gradient). Customize the colors. Download the PNG. Done.

The output is a proper 1200Ã—630 PNG you can drop into any /public folder and reference in your meta tags. No account needed for the free tier.

The meta tags are generated for you automatically â€” you copy them straight into your <head>.

Putting It Together

The full workflow:

Write your article or ship your project
Open OGForge, type your title + description
Pick a template, hit download
Upload the PNG to your /public folder or CDN
Paste the generated meta tags into your <head>, update the image URL
Done â€” every platform will now show a clean preview card

Total time: under 5 minutes. Traffic impact: measurable.

Your content is good. Stop letting a missing 1200Ã—630 PNG be the reason nobody clicks.

I Built a Tool That Kills Scope Creep for Freelancers

Maxwell Smart — Mon, 23 Mar 2026 12:09:34 +0000

The $500 conversation you never saw coming

You quoted $2,500 for a website redesign. Three pages, two revision rounds, delivered in three weeks. The client agreed.

Two weeks in: "Can you also add a blog section? I figured that was part of the redesign."

It wasn't. But you didn't have anything in writing — just a verbal agreement and a Slack thread buried under 200 messages. So you eat the extra work, resent the project, and swear you'll "get better at contracts" next time.

Most freelancers have this conversation at least once a quarter. The ones who don't? They have a signed scope.

The problem with contracts

Traditional contracts are overkill for a $2,000 project. They're expensive to draft, intimidating to clients, and nobody reads them. What freelancers actually need is a lightweight way to:

List exactly what they're delivering
Get the client to acknowledge it in writing
Have a reference point when "can you also..." starts

That's it. Not a 12-page legal document. Just a clear scope with a signature.

What I built

ScopeGuard generates a shareable scope agreement in 60 seconds. You fill in the project details — deliverables, price, timeline, revisions, out-of-scope clause — and it generates a link.

Send the link to your client. They see the full scope document, type their name, check the agreement box, and sign. The scope locks. Any changes require a formal amendment.

The entire thing runs client-side. No database, no sign-ups, no tracking. The scope data lives in the URL itself. You can save the signed scope as a PDF for your records.

How it works technically

The scope data is base64-encoded into the URL hash. When your client opens the link, the page decodes the data and renders the scope document. When they sign, the signature (name + timestamp) is added to the data and the URL updates.

No server required. Works offline. Privacy by design.

Why this matters

Scope creep isn't just annoying — it's a direct hit to your hourly rate. A $2,500 project that takes 50% more work because of uncontrolled scope means you're effectively earning 33% less per hour.

The fix takes 60 seconds: define the scope, send the link, get the sign-off. Now when the client asks for something extra, you point to the signed agreement and discuss an amendment.

Ready to eliminate scope creep? ScopeGuard Pro: $9/mo, unlimited scopes. Agency: $49/mo, team collaboration. Try free: https://scopeguard-red.vercel.app