add swagger documentation to api

Author: youngkiu

.env

@@ -1,6 +1,6 @@
-# docker-compose config
-WEB_PORT=80
+VERSION=0.7
 
+WEB_PORT=80
 APP_PORT=5000
 
 DB_NAME=company

README.md

@@ -1,3 +1,10 @@
+## Quick start
+
+```shell
+$ docker-compose up
+```
+Connect **http://localhost/api**
+
 ## How to develop
 
 ```shell
@@ -18,8 +25,8 @@ app$ DEBUG=1 python $PWD/app.py
 ```shell
 $ curl -i -X GET http://localhost:5000/api/company?name=Agi
 $ curl -i -X GET http://localhost:5000/api/company?tag=tag_26
-$ curl -i -X PUT -H "Content-Type: application/json" -d '{"name": "infobank", "language": "en", "tag": "tag_5"}' http://localhost:5000/api/company
-$ curl -i -X DELETE -H "Content-Type: application/json" -d '{"name": "infobank", "language": "en", "tag": "tag_5"}' http://localhost:5000/api/company
+$ curl -i -X PUT -H "Content-Type: application/json" -d '{"language": "en", "name": "infobank", "tag": "tag_5"}' http://localhost:5000/api/company
+$ curl -i -X DELETE -H "Content-Type: application/json" -d '{"language": "en", "name": "infobank", "tag": "tag_5"}' http://localhost:5000/api/company
 ```
 
 ## How to run

app/app.py

@@ -1,7 +1,6 @@
-from flask import Flask, request, jsonify, abort
-from flask_restful import Api,Resource
-from functools import wraps
-from config import SQLALCHEMY_DATABASE_URI, SECRET_KEY
+from flask import Flask, jsonify, abort
+from flask_restx import Api, Resource, reqparse
+from config import VERSION, SQLALCHEMY_DATABASE_URI, SECRET_KEY
 from models import db, Company, Language, CompanyName, CompanyTag
 
 
@@ -12,28 +11,45 @@
 app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = True
 
 db.init_app(app)
-api = Api(app)
+api = Api(app,
+          version=VERSION, title='Company API',
+          description='A company name & tag API',
+          doc='/api')
 
 
-def check_name_language(func):
-    @wraps(func)
-    def wrapper(*args, **kwargs):
-        return func(*args, **kwargs)
+read_parser = reqparse.RequestParser()
+read_parser.add_argument('name', type=str, location='args', help='Company Name')
+read_parser.add_argument('tag', type=str, location='args', help='Company Tag')
 
-    return wrapper
+write_parser = reqparse.RequestParser()
+write_parser.add_argument('language', required=True,
+                          type=str, location='json', help='Country Code')
+write_parser.add_argument('name', required=True,
+                          type=str, location='json', help='Company Name')
+write_parser.add_argument('tag', required=True,
+                          type=str, location='json', help='Company Tag')
 
 
+@api.route('/api/company')
 class ApiCompany(Resource):
+    @api.expect(read_parser)
+    @api.doc(responses={
+        200: 'Success',
+        400: 'Validation Error'
+    })
     def get(self):
-        name = request.args.get('name')
+        args = read_parser.parse_args()
+        print(args)
+
+        name = args['name']
         if name:
             company_name = CompanyName.query \
                 .filter(CompanyName.name.like('%{}%'.format(name))) \
                 .first()
             if company_name:
                 return company_name.name
 
-        tag = request.args.get('tag')
+        tag = args['tag']
         if tag:
             companies = Company.query \
                 .join(CompanyTag) \
@@ -51,14 +67,20 @@ def get(self):
             print(results)
             return jsonify(results)
 
+        abort(status=400, description='No arguments')
+
+    @api.expect(write_parser)
+    @api.doc(responses={
+        200: 'Success',
+        400: 'Validation Error'
+    })
     def put(self):
-        req_data = request.get_json()
-        if req_data is None or any(key not in req_data for key in ('name', 'language', 'tag')):
-            abort(status=400, description='Invalid request data')
+        args = write_parser.parse_args()
+        print(args)
 
-        name = req_data['name']
-        country_code = req_data['language']
-        tag = req_data['tag']
+        country_code = args['language']
+        name = args['name']
+        tag = args['tag']
 
         company_names = CompanyName.query \
             .filter_by(name=name) \
@@ -76,7 +98,7 @@ def put(self):
             db.session.commit()
             print('language', language.id)
 
-        results = {'updated': []}
+        results = {'Updated': []}
         for company_name in company_names:
             company_tag = CompanyTag.query \
                 .filter_by(
@@ -91,19 +113,23 @@ def put(self):
                 db.session.commit()
                 print('company_tag', company_tag.id)
 
-            results['updated'].append({name: tag})
+            results['Updated'].append({name: tag})
 
         print(results)
         return jsonify(results)
 
+    @api.expect(write_parser)
+    @api.doc(responses={
+        200: 'Success',
+        400: 'Validation Error'
+    })
     def delete(self):
-        req_data = request.get_json()
-        if req_data is None or any(key not in req_data for key in ('name', 'language', 'tag')):
-            abort(status=400, description='Invalid request data')
+        args = write_parser.parse_args()
+        print(args)
 
-        name = req_data['name']
-        country_code = req_data['language']
-        tag = req_data['tag']
+        country_code = args['language']
+        name = args['name']
+        tag = args['tag']
 
         company_names = CompanyName.query \
             .filter_by(name=name) \
@@ -121,7 +147,7 @@ def delete(self):
             db.session.commit()
             print('language', language.id)
 
-        results = {'deleted': []}
+        results = {'Deleted': []}
         for company_name in company_names:
             company_tag = CompanyTag.query \
                 .filter_by(
@@ -135,14 +161,11 @@ def delete(self):
                 db.session.commit()
                 print('company_tag', company_tag.id)
 
-            results['deleted'].append({name: tag})
+            results['Deleted'].append({name: tag})
 
         print(results)
         return jsonify(results)
 
 
-api.add_resource(ApiCompany, '/api/company')
-
-
 if __name__ == '__main__':
     app.run(host='0.0.0.0', debug=True)

app/config.py

@@ -1,7 +1,7 @@
 import os
 
 if 'DEBUG' in os.environ:
-    print('[Debug] Local debug mode')
+    print('[Debug] development mode')
 
     from dotenv import load_dotenv
 
@@ -10,7 +10,10 @@
     load_dotenv(dotenv_path=env_path)
 
     os.environ['DB_SERVER'] = '127.0.0.1'
+else:
+    print('[Debug] production mode')
 
+VERSION = os.environ['VERSION']
 SECRET_KEY = os.environ['SECRET_KEY']
 DB_USER = os.environ['DB_USER']
 DB_PASS = os.environ['DB_PASS']

app/requirements.txt

@@ -1,26 +1,29 @@
-alembic==1.5.4
+alembic==1.5.5
 aniso8601==9.0.0
+attrs==20.3.0
 autopep8==1.5.4
 certifi==2020.12.5
 click==7.1.2
 Flask==1.1.2
 Flask-Migrate==2.6.0
-Flask-RESTful==0.3.8
+flask-restx==0.2.0
 Flask-Script==2.0.6
 Flask-SQLAlchemy==2.4.4
 itsdangerous==1.1.0
 Jinja2==2.11.3
+jsonschema==3.2.0
 Mako==1.1.4
 MarkupSafe==1.1.1
 numpy==1.20.1
 pandas==1.2.2
 psycopg2-binary==2.8.6
 pycodestyle==2.6.0
+pyrsistent==0.17.3
 python-dateutil==2.8.1
 python-dotenv==0.15.0
 python-editor==1.0.4
 pytz==2021.1
 six==1.15.0
 SQLAlchemy==1.3.23
 toml==0.10.2
-Werkzeug==1.0.1
+Werkzeug==0.16.1

docker-compose.yml

@@ -14,7 +14,7 @@ services:
       - ./nginx/nginx.conf.template:/etc/nginx/nginx.conf.template:ro
       - ./nginx/run_nginx.sh:/opt/nginx/run_nginx.sh
     ports:
-      - ${WEB_PORT}:80
+      - $WEB_PORT:80
     environment:
       - NGINX_PORT=80
       - APP_SERVICE=project-app
@@ -25,21 +25,22 @@ services:
 
   app:
     container_name: project-app
-    image: project_app:0.3
+    image: project_app:$VERSION
     build:
       context: app/
       dockerfile: Dockerfile
     networks:
       - project_net
     ports:
-      - ${APP_PORT}:5000
+      - $APP_PORT:5000
     environment:
-      - DB_USER=${DB_USER}
-      - DB_PASS=${DB_PASS}
+      - VERSION=$VERSION
+      - DB_USER=$DB_USER
+      - DB_PASS=$DB_PASS
       - DB_SERVER=project-db
       - DB_PORT=5432
-      - DB_NAME=${DB_NAME}
-      - SECRET_KEY=${SECRET_KEY}
+      - DB_NAME=$DB_NAME
+      - SECRET_KEY=$SECRET_KEY
     volumes:
       - ./db/:/opt/project/db/
     command: /bin/bash -c "./wait-for-postgres.sh db 5432 && ./migrate.sh /opt/project/db/migrations/ && python app.py"
@@ -52,10 +53,10 @@ services:
     networks:
       - project_net
     ports:
-      - ${DB_PORT}:5432
+      - $DB_PORT:5432
     environment:
-      - POSTGRES_PASSWORD=${DB_PASS}
-      - POSTGRES_USER=${DB_USER}
-      - POSTGRES_DB=${DB_NAME}
+      - POSTGRES_PASSWORD=$DB_PASS
+      - POSTGRES_USER=$DB_USER
+      - POSTGRES_DB=$DB_NAME
     volumes:
       - ./db/data/:/var/lib/postgresql/data/