このページについて
Macとvscode に swagger の開発環境を構築し、api document を作るまでが書いてあります
背景
api仕様書を書くのにblueprintを使っていますが、他のも試してみたくなったからです(私が選定していないため)
agreedという定義を簡単にかけるやつ使ってみましたが
制約などの書き込みができなかったので採用を見送りました(必須制約入れられないの辛い)
ゴール
こんなドキュメントが作れるようになります
手順
vscodeの設定
- yaml extention のインストール
- 設定ファイルに追加記述
"yaml.schemas": {
"https://raw.githubusercontent.com/kogosoftwarellc/open-api/master/packages/openapi-schema-validator/resources/openapi-3.0.json": ["*swagger.yaml", "*swagger.yml"],
},
- swagger viewer のインストール
- Shift + Alt + P でyamlに記述したdocのpreviewが可能になります
書き方
yamlの内容をhtmlにしたい
誰かに渡すときに必要ですよね
$ docker run -i yousan/swagger-yaml-to-html < your-swagger.yml > ./build/index.html
swagger-codegenのインストール
(クライアントなど必要であれば)
$ brew cask install adoptopenjdk8 && \
brew instal swagger-codegen