Feature/add swagger

README.md

@@ -4,6 +4,8 @@
 PHPでエンドポイント(APIにアクセスするためのURI)を定義して、
 フロントエンドから呼び出す想定をしてます
 
+[API定義はこちら](https://github.com/acio-o9/knowledge_browser#about_APIs)
+
 phpは7.4、Mysqlは5.7系で動いています。Laravelは7系を入れました。
 
 ```
@@ -57,3 +59,28 @@ GUIツールなどで見る場合は下記とenvファイルのユーザで接
 ホスト: 127.0.0.1
 ポート: 3306
 
+# about APIs
+
+提供するAPIを下記ファイルで定義している
+
+- /api.yml
+
+## swagger-editor
+
+ymlファイル編集に利用する
+
+```
+http://localhost:8001
+```
+
+画面上部のmenuより、import yml fileを選択して編集する
+
+// FIXME マウントして更新できるようにしたい
+
+## swagger-ui
+
+editor機能をなくしたもの
+
+```
+http://localhost:8002
+```

api.yml

@@ -0,0 +1,130 @@
+openapi: 3.0.0
+
+info:
+  title: Knowledge Browser
+  description: "This product can share cards: Word-Explanation lists for learning new knowledge.
+    If you get new knowledge, write a card on `Knowledge Browser`.
+    The card is checked by another member, add to card lists with member agreement.
+    All member using `Knowledge Browser` meets the card someday."
+  contact:
+    name: acio-o9
+    url: https://github.com/acio-o9
+  version: 1.0.0
+
+servers:
+  - url: http://localhost:8081
+    description: Development server
+
+paths:
+  /cards:
+    get:
+      summary: List all Cards.
+      description: Returns an array of Card model
+      tags:
+        - cards
+      responses:
+        '200':
+          description: A JSON array of Card model
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Card'
+                example:
+                  - id: 1
+                    word: LGTM
+                    explanation: Looks Good To Me
+                  - id: 2
+                    word: YAGNI
+                    explanation: You ain't gonna need it
+    post:
+      summary: Create a Card
+      description: Create new Card
+      tags:
+        - cards
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Card'
+            examples:
+              card:
+                word: LGTM
+                explanation: Looks Good To Me
+      responses:
+        '201':
+          description: CREATED
+
+  /cards/{cardId}:
+    get:
+      summary: Info for a specific card
+      description: Returns a single Card model
+      tags:
+        - cards
+      parameters:
+        - name: cardId
+          in: path
+          required: true
+          description: The id of the card to retrieve
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Card'
+
+    post:
+      summary: Updata a card Infomation
+      description: Update a card Infomation
+      tags:
+        - cards
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Card'
+            examples:
+              card:
+                id: 1
+                word: LGTM
+                explanation: Looks Good To Me
+      responses:
+        '200':
+          description: Expected response to a valid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Card'
+
+    delete:
+      summary: Delete a card
+      description: Process to delete a card
+      tags:
+        - cards
+      parameters:
+        - name: cardId
+          in: path
+          required: true
+          description: The id of the card to retrieve
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Expected response to a valid request
+
+components:
+  schemas:
+    Card:
+      type: object
+      properties:
+        id:
+          type: integer
+          format: int64
+        word:
+          type: string
+        explanation:
+          type: string

docker-compose.yml

@@ -2,11 +2,12 @@ version: '3'
 
 services :
   app:
+    container_name: app
     build:
-        context: ./
-        dockerfile: ./docker/Dockerfile
+      context: ./
+      dockerfile: ./docker/Dockerfile
     ports:
-        - '8081:80'
+      - '8081:80'
     volumes:
       - ./application:/var/www/application
     env_file:
@@ -15,6 +16,7 @@ services :
     stdin_open: true
 
   mysql:
+    container_name: mysql
     image: mysql:5.7
     volumes:
       - ./docker/mysql/conf.d:/etc/mysql/conf.d
@@ -25,3 +27,19 @@ services :
       MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
     ports:
       - '3306:3306'
+
+  swagger-editor:
+    image: swaggerapi/swagger-editor
+    container_name: swagger-editor
+    ports:
+      - "8001:8080"
+
+  swagger-ui:
+    image: swaggerapi/swagger-ui
+    container_name: swagger-ui
+    ports:
+      - "8002:8080"
+    volumes:
+      - "./api.yml:/api.yml"
+    environment:
+      SWAGGER_JSON: /api.yml