Swaggerとは、RESTful APIを定義するフォーマットであるOpenAPI仕様に基づき構築された、API仕様書を記述・作成するための一連のオープンソースツールの総称。
SwaggerはREST APIの仕様書を作成してくれるフレームワーク
機能
個人利用用のSwagger
- Swagger Editor・・・API仕様書を書くためのエディタ
https://editor.swagger.io/ - Swagger UI・・・API仕様書からドキュメントを生成する
https://swagger.io/tools/swagger-ui/ - Swagger Codegen・・・API仕様書からコードを生成する
VS Code拡張機能
- OpenAPI (Swagger) Editor
クラウドでのバージョン管理・共有ツール
- SwaggerHub
使い方
VS Code拡張機能 OpenAPI (Swagger) Editor
- OPEN APIの拡張機能のボタンを押す
- New OpenAPI fileを押す
- 適当にAPIのJSONを修正する
- 適当なフォルダにYAMLを保存する
- Ctrl+Shift+Pを押す
- Preview Swaggerを実行する
できるのはtry it outでAPIの検証と仕様書のプレヴューまで
デプロイは別の方法
sample.yaml
openapi: '3.0.2'
info:
title: API Title
version: '1.0'
description: |-
This is a sample Pet Store Server based on the OpenAPI 3.0 specification. You can find out more about
Swagger at [https://swagger.io](https://swagger.io). In the third iteration of the pet store, we've switched to the design first approach!
You can now help us improve the API whether it's by making changes to the definition itself or to the code.
That way, with time, we can improve the API in general, and expose some of the new features in OAS3.
_If you're looking for the Swagger 2.0/OAS 2.0 version of Petstore, then click [here](https://editor.swagger.io/?url=https://petstore.swagger.io/v2/swagger.yaml). Alternatively, you can load via the `Edit > Load Petstore OAS 2.0` menu option!_
Some useful links:
- [The Pet Store repository](https://github.com/swagger-api/swagger-petstore)
- [The source API definition for the Pet Store](https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml)
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Find out more about Swagger
url: http://swagger.io
servers:
- url: https://api.server.test/v1
- url: https://api.server.test/v2
- url: https://api.server.test/v3
tags:
- name: test
description: Everything about your Pets
externalDocs:
description: Find out more
url: http://swagger.io
- name: app
description: Access to Petstore orders
externalDocs:
description: Find out more about our store
url: http://swagger.io
- name: user
description: Operations about user
paths:
/test:
get:
tags:
- test
responses:
'200':
description: OK
put:
tags:
- test
description: ''
parameters: []
responses:
'200':
description: OK
delete:
tags:
- test
description: ''
parameters: []
responses:
'200':
description: OK
post:
tags:
- test
description: ''
parameters: []
responses:
'200':
description: OK
/app:
get:
tags:
- app
description: ''
parameters: []
responses:
'200':
description: OK
put:
tags:
- app
description: ''
parameters: []
responses:
'200':
description: OK
/val:
get:
tags:
- val
description: ''
parameters: []
responses:
'200':
description: OK
security:
- aaa: [aaa]
YAML形式の仕様書のWebページをデプロイ
Swagger UI
- index.htmlを作成して、エディターで開く
- 下記をコピペする
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content="SwaggerUI" />
<title>SwaggerUI</title>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui.css" />
</head>
<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@5.11.0/swagger-ui-bundle.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
url: 'path to yaml',
dom_id: '#swagger-ui',
});
};
</script>
</body>
</html>
- url: 'path to yaml',をurl: 'http://127.0.0.1:5500/OpenAPI/sample.yaml', のようにサーバーURLへ変更する
仕様書のWebページを参照するには、サーバーを立てる必要がある。
VS CodeのLive Server等で簡単に検証可能
