2023-07-18 18:38:30 +00:00
|
|
|
<!doctype html>
|
2023-05-23 10:06:33 +00:00
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<meta charset="utf-8" />
|
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
|
|
|
<link
|
|
|
|
|
rel="stylesheet"
|
2024-02-04 15:04:33 +00:00
|
|
|
href="https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.5.1/github-markdown.min.css"
|
2023-05-23 10:06:33 +00:00
|
|
|
/>
|
|
|
|
|
<title>haunt98 posts</title>
|
|
|
|
|
</head>
|
|
|
|
|
<style>
|
|
|
|
|
.markdown-body {
|
|
|
|
|
box-sizing: border-box;
|
|
|
|
|
min-width: 200px;
|
|
|
|
|
max-width: 980px;
|
|
|
|
|
margin: 0 auto;
|
|
|
|
|
padding: 45px;
|
2024-03-01 10:11:20 +00:00
|
|
|
font-family:
|
|
|
|
|
Shantell Sans Normal,
|
|
|
|
|
Rec Mono Casual,
|
|
|
|
|
SF Pro,
|
|
|
|
|
Inter,
|
|
|
|
|
sans-serif;
|
|
|
|
|
font-weight: 500;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
.markdown-body pre {
|
|
|
|
|
font-family:
|
|
|
|
|
Berkeley Mono,
|
|
|
|
|
IBM Plex Mono,
|
|
|
|
|
SF Mono,
|
|
|
|
|
Jetbrains Mono,
|
|
|
|
|
monospace;
|
2023-05-23 10:06:33 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@media (max-width: 767px) {
|
|
|
|
|
.markdown-body {
|
|
|
|
|
padding: 15px;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
</style>
|
|
|
|
|
<body class="markdown-body">
|
2023-08-09 07:22:58 +00:00
|
|
|
<h2>
|
|
|
|
|
<a href="index.html"><code>~</code></a>
|
|
|
|
|
</h2>
|
2024-02-29 12:29:26 +00:00
|
|
|
<div class="markdown-heading">
|
|
|
|
|
<h1 class="heading-element">Swagger or OpenAPI</h1>
|
2023-11-19 15:59:21 +00:00
|
|
|
<a
|
|
|
|
|
id="user-content-swagger-or-openapi"
|
2024-03-08 08:12:41 +00:00
|
|
|
class="anchor"
|
2024-02-29 12:29:26 +00:00
|
|
|
aria-label="Permalink: Swagger or OpenAPI"
|
2023-11-19 15:59:21 +00:00
|
|
|
href="#swagger-or-openapi"
|
2024-02-29 12:29:26 +00:00
|
|
|
><span aria-hidden="true" class="octicon octicon-link"></span
|
|
|
|
|
></a>
|
|
|
|
|
</div>
|
2023-05-23 10:06:33 +00:00
|
|
|
<p>My company currently use Swagger 2 to document API.</p>
|
|
|
|
|
<p>
|
|
|
|
|
I want to work with OpenAPI 3 but too lazy to convert (for now of course).
|
|
|
|
|
</p>
|
|
|
|
|
<p>So step by step:</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Write API spec in <code>YAML</code>.</li>
|
|
|
|
|
<li>Convert to API spec in <code>JSON</code>.</li>
|
|
|
|
|
<li>Format spec files.</li>
|
|
|
|
|
<li>Render spec in local.</li>
|
|
|
|
|
<li>Push to company host for other teams to see.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
Only step 1 is manual, aka I write my API spec completely with my hand (no
|
|
|
|
|
auto gen from code whatever). The others can be done with tools:
|
|
|
|
|
</p>
|
|
|
|
|
<div class="highlight highlight-source-shell">
|
|
|
|
|
<pre><span class="pl-c"><span class="pl-c">#</span> Convert</span>
|
|
|
|
|
go install github.com/mikefarah/yq/v4@latest
|
|
|
|
|
yq -o=json <span class="pl-s"><span class="pl-pds">'</span>.<span class="pl-pds">'</span></span> ./docs/swagger.yaml <span class="pl-k">></span> ./docs/swagger.json
|
|
|
|
|
|
|
|
|
|
<span class="pl-c"><span class="pl-c">#</span> Format</span>
|
2023-12-01 10:25:52 +00:00
|
|
|
bunx prettier@latest --write ./docs/swagger.yaml ./docs/swagger.json
|
2023-05-23 10:06:33 +00:00
|
|
|
|
|
|
|
|
<span class="pl-c"><span class="pl-c">#</span> Render locally</span>
|
|
|
|
|
bunx @redocly/cli preview-docs ./docs/swagger.json</pre>
|
|
|
|
|
</div>
|
2024-02-29 12:29:26 +00:00
|
|
|
<div class="markdown-heading">
|
|
|
|
|
<h2 class="heading-element">Thanks</h2>
|
2023-11-19 15:59:21 +00:00
|
|
|
<a
|
|
|
|
|
id="user-content-thanks"
|
2024-03-08 08:12:41 +00:00
|
|
|
class="anchor"
|
2024-02-29 12:29:26 +00:00
|
|
|
aria-label="Permalink: Thanks"
|
2023-11-19 15:59:21 +00:00
|
|
|
href="#thanks"
|
2024-02-29 12:29:26 +00:00
|
|
|
><span aria-hidden="true" class="octicon octicon-link"></span
|
|
|
|
|
></a>
|
|
|
|
|
</div>
|
2023-05-23 10:06:33 +00:00
|
|
|
<ul>
|
|
|
|
|
<li><a href="https://github.com/mikefarah/yq">mikefarah/yq</a></li>
|
|
|
|
|
<li><a href="https://github.com/oven-sh/bun">oven-sh/bun</a></li>
|
|
|
|
|
<li>
|
|
|
|
|
<a href="https://github.com/prettier/prettier">prettier/prettier</a>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<a href="https://github.com/Redocly/redocly-cli">Redocly/redocly-cli</a>
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<div>
|
|
|
|
|
Feel free to ask me via
|
|
|
|
|
<a href="mailto:hauvipapro+posts@gmail.com">email</a> or
|
2023-08-20 17:29:13 +00:00
|
|
|
<a rel="me" href="https://hachyderm.io/@haunguyen">Mastodon</a>.
|
|
|
|
|
<br />Source code is available on
|
2023-05-23 10:06:33 +00:00
|
|
|
<a href="https://github.com/haunt98/posts-go">GitHub</a>
|
2023-08-20 17:29:13 +00:00
|
|
|
<a href="https://codeberg.org/yoshie/posts-go">Codeberg</a>
|
|
|
|
|
<a href="https://git.sr.ht/~youngyoshie/posts-go">sourcehut</a>
|
|
|
|
|
<a href="https://gitea.treehouse.systems/yoshie/posts-go">Treehouse</a>
|
|
|
|
|
<a href="https://gitlab.com/youngyoshie/posts-go">GitLab</a>
|
2023-05-23 10:06:33 +00:00
|
|
|
</div>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
