diff --git a/docs/2023-05-23-swagger.html b/docs/2023-05-23-swagger.html new file mode 100644 index 0000000..e727bb8 --- /dev/null +++ b/docs/2023-05-23-swagger.html @@ -0,0 +1,108 @@ + + + + + + + + + + haunt98 posts + + + +
Index
+

+ Swagger or OpenAPI +

+

My company currently use Swagger 2 to document API.

+

+ I want to work with OpenAPI 3 but too lazy to convert (for now of course). +

+

So step by step:

+ +

+ 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: +

+
+ 
# Convert
+go install github.com/mikefarah/yq/v4@latest
+yq -o=json '.' ./docs/swagger.yaml > ./docs/swagger.json
+
+# Format
+bunx prettier --write ./docs/swagger.yaml ./docs/swagger.json
+
+# Render locally
+bunx @redocly/cli preview-docs ./docs/swagger.json
+
+

+ Thanks +

+ + +
+ Feel free to ask me via + email or + Mastodon. Source + code is available on + GitHub +
+ + diff --git a/docs/index.html b/docs/index.html index 65f06c8..726a5ee 100644 --- a/docs/index.html +++ b/docs/index.html @@ -67,6 +67,7 @@
  • Keeb
  • My neovim workflow
  • Things I like
    • +
  • Swagger or OpenAPI
    • diff --git a/posts/2023-05-23-swagger.md b/posts/2023-05-23-swagger.md new file mode 100644 index 0000000..470a9d8 --- /dev/null +++ b/posts/2023-05-23-swagger.md @@ -0,0 +1,35 @@ +# Swagger or OpenAPI + +My company currently use Swagger 2 to document API. + +I want to work with OpenAPI 3 but too lazy to convert (for now of course). + +So step by step: + +- Write API spec in `YAML`. +- Convert to API spec in `JSON`. +- Format spec files. +- Render spec in local. +- Push to company host for other teams to see. + +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: + +```sh +# Convert +go install github.com/mikefarah/yq/v4@latest +yq -o=json '.' ./docs/swagger.yaml > ./docs/swagger.json + +# Format +bunx prettier --write ./docs/swagger.yaml ./docs/swagger.json + +# Render locally +bunx @redocly/cli preview-docs ./docs/swagger.json +``` + +## Thanks + +- [mikefarah/yq](https://github.com/mikefarah/yq) +- [oven-sh/bun](https://github.com/oven-sh/bun) +- [prettier/prettier](https://github.com/prettier/prettier) +- [Redocly/redocly-cli](https://github.com/Redocly/redocly-cli) diff --git a/posts/index.md b/posts/index.md index fd7ceac..016fec7 100644 --- a/posts/index.md +++ b/posts/index.md @@ -20,3 +20,4 @@ This is where I dump my thoughts. - [Keeb](2023-04-17-keeb.html) - [My neovim workflow](2023-05-03-neovim.html) - [Things I like](2023-05-08-things-i-like.html) +- [Swagger or OpenAPI](2023-05-23-swagger.html)