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等で簡単に検証可能