Skip to content

Commit 615019a

Browse files
shivaamshivaam
committed
Add static Pages HTML entrypoints
1 parent b561543 commit 615019a

4 files changed

Lines changed: 250 additions & 0 deletions

File tree

‎docs/blog/openapi-spec-to-cli.html‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>Turn an OpenAPI Spec Into a CLI People Can Actually Use</title>
7+
<meta name="description" content="OpenAPI specs are not only for SDKs and docs. They can generate human-facing Python CLIs with typed flags and nested request bodies flattened into command options.">
8+
<style>
9+
body {
10+
font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
11+
line-height: 1.65;
12+
margin: 0;
13+
background: #f7f7f4;
14+
color: #161616;
15+
}
16+
main {
17+
max-width: 820px;
18+
margin: 0 auto;
19+
padding: 48px 20px 72px;
20+
}
21+
h1 {
22+
font-size: clamp(2rem, 5vw, 3.8rem);
23+
line-height: 1.05;
24+
letter-spacing: 0;
25+
}
26+
h2 {
27+
margin-top: 42px;
28+
}
29+
p, li {
30+
font-size: 1.05rem;
31+
}
32+
.back {
33+
margin-bottom: 32px;
34+
}
35+
a {
36+
color: #0f766e;
37+
text-underline-offset: 0.18em;
38+
}
39+
pre {
40+
background: #202124;
41+
color: #f8f8f2;
42+
overflow-x: auto;
43+
padding: 18px;
44+
border-radius: 8px;
45+
}
46+
code {
47+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
48+
}
49+
@media (prefers-color-scheme: dark) {
50+
body {
51+
background: #111;
52+
color: #f3f3f0;
53+
}
54+
a {
55+
color: #5eead4;
56+
}
57+
pre {
58+
background: #050505;
59+
}
60+
}
61+
</style>
62+
</head>
63+
<body>
64+
<main>
65+
<p class="back"><a href="../index.html">Back to openapi-cli-gen</a></p>
66+
<h1>Turn an OpenAPI Spec Into a CLI People Can Actually Use</h1>
67+
<p>Most teams already have more API structure than they use.</p>
68+
<p>If you have a FastAPI app, a Swagger spec, or any OpenAPI 3.x document, the spec already knows your paths, methods, query parameters, path parameters, request bodies, auth schemes, enums, and validation rules.</p>
69+
<p>And yet, a lot of internal API workflows still end up as copied <code>curl</code> commands:</p>
70+
<pre><code>curl -X POST "$API_URL/users" \
71+
-H "Authorization: Bearer $TOKEN" \
72+
-H "Content-Type: application/json" \
73+
-d '{"name":"Jane","email":"jane@example.com","address":{"city":"NYC","state":"NY"}}'</code></pre>
74+
<p>That works, but it is not a great interface. It is easy to mistype. It is hard to discover. It asks humans to write JSON even when the schema already knows the fields.</p>
75+
<p>I built <a href="https://github.com/shivaam/openapi-cli-gen">openapi-cli-gen</a> to explore a narrower idea: what if an OpenAPI spec could become a human-facing command line app?</p>
76+
77+
<h2>The Basic Idea</h2>
78+
<p>Instead of making users paste JSON, generate commands like this:</p>
79+
<pre><code>mycli users create \
80+
--name Jane \
81+
--address.city NYC \
82+
--address.state NY</code></pre>
83+
<p>The OpenAPI spec provides the structure. The generated CLI exposes that structure as command groups, options, environment variables, and output formats.</p>
84+
85+
<h2>Why Not Just Use OpenAPI Generator?</h2>
86+
<p>OpenAPI Generator is excellent when you need SDKs, server stubs, models, or language-specific client libraries. That is not the same job.</p>
87+
<p>The distinction is:</p>
88+
<pre><code>SDK generator: produce code developers import.
89+
CLI generator: produce commands humans and scripts run.</code></pre>
90+
91+
<h2>FastAPI Is A Natural Fit</h2>
92+
<p>FastAPI publishes an OpenAPI spec at <code>/openapi.json</code> by default. That means a running FastAPI app can become a CLI without adding a separate API description file:</p>
93+
<pre><code>openapi-cli-gen generate \
94+
--spec http://localhost:8000/openapi.json \
95+
--name internal-admin</code></pre>
96+
97+
<h2>Nested Request Bodies Are The Pain Point</h2>
98+
<p>The easy part of an API CLI is path and query parameters. The annoying part is request bodies.</p>
99+
<pre><code>internal-admin users create \
100+
--name Jane \
101+
--email jane@example.com \
102+
--address.city NYC \
103+
--address.state NY</code></pre>
104+
<p>For complex cases, JSON fallback is still available:</p>
105+
<pre><code>internal-admin users create \
106+
--address '{"city":"NYC","state":"NY"}'</code></pre>
107+
108+
<h2>Try It</h2>
109+
<pre><code>pipx install openapi-cli-gen
110+
111+
openapi-cli-gen inspect \
112+
--spec https://petstore3.swagger.io/api/v3/openapi.json</code></pre>
113+
<p>Project: <a href="https://github.com/shivaam/openapi-cli-gen">https://github.com/shivaam/openapi-cli-gen</a></p>
114+
<p>I am especially interested in real OpenAPI specs that make generated CLIs awkward: unusual auth, nested bodies, arrays of objects, multipart uploads, unions, or very large schemas.</p>
115+
</main>
116+
</body>
117+
</html>

‎docs/index.html‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1">
6+
<title>openapi-cli-gen: Generate Python CLIs from OpenAPI specs</title>
7+
<meta name="description" content="Generate human-facing Python command line apps from OpenAPI, Swagger, and FastAPI specs. Nested request bodies become dot flags.">
8+
<style>
9+
:root {
10+
color-scheme: light dark;
11+
--bg: #f7f7f4;
12+
--fg: #161616;
13+
--muted: #5a5a5a;
14+
--line: #d8d8d0;
15+
--code: #202124;
16+
--code-fg: #f8f8f2;
17+
--accent: #0f766e;
18+
}
19+
@media (prefers-color-scheme: dark) {
20+
:root {
21+
--bg: #111;
22+
--fg: #f3f3f0;
23+
--muted: #b8b8b0;
24+
--line: #333;
25+
--code: #050505;
26+
--code-fg: #f8f8f2;
27+
--accent: #5eead4;
28+
}
29+
}
30+
body {
31+
background: var(--bg);
32+
color: var(--fg);
33+
font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
34+
line-height: 1.6;
35+
margin: 0;
36+
}
37+
main {
38+
max-width: 860px;
39+
margin: 0 auto;
40+
padding: 56px 20px 72px;
41+
}
42+
h1 {
43+
font-size: clamp(2.2rem, 6vw, 4.6rem);
44+
line-height: 1;
45+
margin: 0 0 18px;
46+
letter-spacing: 0;
47+
}
48+
h2 {
49+
border-top: 1px solid var(--line);
50+
margin-top: 42px;
51+
padding-top: 28px;
52+
}
53+
p, li {
54+
font-size: 1.05rem;
55+
}
56+
.lead {
57+
color: var(--muted);
58+
font-size: 1.25rem;
59+
max-width: 720px;
60+
}
61+
a {
62+
color: var(--accent);
63+
text-decoration-thickness: 0.08em;
64+
text-underline-offset: 0.18em;
65+
}
66+
pre {
67+
background: var(--code);
68+
color: var(--code-fg);
69+
overflow-x: auto;
70+
padding: 18px;
71+
border-radius: 8px;
72+
}
73+
code {
74+
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
75+
}
76+
.links {
77+
display: flex;
78+
flex-wrap: wrap;
79+
gap: 12px;
80+
margin: 28px 0;
81+
}
82+
.links a {
83+
border: 1px solid var(--line);
84+
border-radius: 8px;
85+
padding: 10px 14px;
86+
text-decoration: none;
87+
}
88+
</style>
89+
</head>
90+
<body>
91+
<main>
92+
<h1>openapi-cli-gen</h1>
93+
<p class="lead">Generate human-facing Python CLIs from OpenAPI, Swagger, and FastAPI specs. Nested request bodies become dot flags like <code>--address.city NYC</code>.</p>
94+
95+
<div class="links">
96+
<a href="https://github.com/shivaam/openapi-cli-gen">GitHub</a>
97+
<a href="https://pypi.org/project/openapi-cli-gen/">PyPI</a>
98+
<a href="blog/openapi-spec-to-cli.html">Blog post</a>
99+
</div>
100+
101+
<pre><code>pipx install openapi-cli-gen
102+
103+
openapi-cli-gen generate \
104+
--spec https://api.example.com/openapi.json \
105+
--name mycli</code></pre>
106+
107+
<h2>Start Here</h2>
108+
<ul>
109+
<li><a href="guides/generate-cli-from-openapi.md">Generate a CLI from an OpenAPI Spec</a></li>
110+
<li><a href="guides/fastapi-openapi-cli.md">Generate a CLI from a FastAPI App</a></li>
111+
<li><a href="guides/openapi-generator-vs-openapi-cli-gen.md">OpenAPI Generator vs openapi-cli-gen</a></li>
112+
</ul>
113+
114+
<h2>Why This Exists</h2>
115+
<p>OpenAPI specs are usually used to generate SDKs, server stubs, and docs. Those are useful, but they are not the only thing a spec can generate.</p>
116+
<p>For support, ops, QA, demos, and internal admin workflows, a terminal command is often the better interface:</p>
117+
118+
<pre><code>mycli users create \
119+
--name Jane \
120+
--email jane@example.com \
121+
--address.city NYC \
122+
--address.state NY</code></pre>
123+
124+
<p>That is the lane for <code>openapi-cli-gen</code>: not another SDK directory, but commands humans and scripts can run.</p>
125+
126+
<h2>Feedback Wanted</h2>
127+
<p>The most useful feedback is a real OpenAPI spec that makes generated CLIs awkward: unusual auth, nested bodies, arrays of objects, multipart uploads, unions, or very large schemas.</p>
128+
<p><a href="https://github.com/shivaam/openapi-cli-gen/issues/new?template=spec-compatibility-report.yml">Open a spec compatibility report</a> or start from the <a href="https://github.com/shivaam/openapi-cli-gen">GitHub repository</a>.</p>
129+
</main>
130+
</body>
131+
</html>

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Project:
2929
## Blog
3030

3131
- [Turn an OpenAPI Spec Into a CLI People Can Actually Use](blog/2026-05-26-openapi-spec-to-cli.md)
32+
- [HTML version for GitHub Pages](blog/openapi-spec-to-cli.html)
3233

3334
## Why This Exists
3435

‎docs/marketing/tracking.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ paid experiments.
3131
| 2026-05-26 | docs/SEO | Added simple docs homepage for GitHub Pages | `docs/index.md` | Ready if Pages is enabled from `/docs`; live repo Pages currently disabled | Enable GitHub Pages after docs are pushed, then update repo homepage if desired. |
3232
| 2026-05-26 | GitHub Pages | Added Pages workflow and publishing runbook | `.github/workflows/pages.yml`, `docs/pages-publishing.md` | Workflow will publish `docs/` after push to `main` and Pages source is set to GitHub Actions | Push docs, enable Pages, then use Pages URL in blog/community links. |
3333
| 2026-05-26 | GitHub Pages | Enabled live GitHub Pages with `build_type=workflow` via `gh api` | https://shivaam.github.io/openapi-cli-gen/ | Pages enabled; site waits for workflow/docs to be pushed to `main`; stars still 1 | Push `.github/workflows/pages.yml` and `docs/`, then run Pages workflow. |
34+
| 2026-05-26 | GitHub Pages | Switched Pages to branch mode and added static HTML entrypoints | https://shivaam.github.io/openapi-cli-gen/ | Added `docs/index.html` and `docs/blog/openapi-spec-to-cli.html` so Pages can serve without a build step | Push HTML entrypoints and verify the public URL no longer 404s. |
3435

3536
## What To Check
3637

0 commit comments

Comments
 (0)