36 lines
961 B
Markdown
36 lines
961 B
Markdown
|
# 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)
|