acantin/add_swagger

labonneboite/web/api/swagger/company.yml

@@ -0,0 +1,90 @@
+Test
+---
+definitions:
+  Etablissement:
+    type: object
+    properties:
+      siret:
+        type: string
+      name:
+        type: string
+      city:
+        type: string
+      phone:
+        type: string
+      email:
+        type: string
+      lat:
+        type: double
+      lon:
+        type: double
+      distance:
+        type: integer
+      headcount_text:
+        type: string
+
+summary: établissements à fort potentiel d'embauche
+description: |
+  COMPANIES renvoie des informations sur les établissements à fort potentiel d'embauche. La réponse inclut le nom des entreprises ainsi que des informations générales (code NAF, effectif salarié) et des informations de contact (email, télphone lorsqu'elles sont présentes). Les établissements sont classés par score de potentiel d'embauche décroissant (les premiers résultats sont donc les plus prometteurs en terme de potentiel d'embauche).
+parameters:
+  - name: latitude
+    in: query
+    description: Latitude du point géographique de recherche.
+    required: true
+    type: number
+    format: double
+  - name: longitude
+    in: query
+    description: Longitude du point géographique de recherche.
+    required: true
+    type: number
+    format: double
+  - name: rome_codes
+    in: query
+    description: Liste de codes métier "ROME" (ex. "D1101,A1501") ou simplement un seul code métier (ex. "A1501")
+    required: false
+    type: string
+    format: string
+  - name: naf_codes
+    in: query
+    description: Liste de codes de secteur d'activités "NAF" (ex. "1013B,4711B") ou simplement un seul code NAF (ex. "4711B")
+    required: false
+    type: string
+    format: string
+  - name: distance
+    in: query
+    description: Périmètre du rayon de recherche (en km) autour du point géographique défini par le couple (longitude, latitude)
+    required: false
+    type: integer
+    format: integer
+  - name: user
+    in: query
+    description: Nom du compte utilisateur API (ex. "labonneformation")
+    required: true
+    type: string
+    format: string
+  - name: timestamp
+    in: query
+    description: date et heure UTC (méridien de Greenwich) au format %Y-%m-%dT%H:%M:%S (ex. "2016-01-05T11:00:22"). Pour être autorisé la différence entre le timestamp serveur et le timestamp fourni par ce paramètre doit être inférieure à 10 minutes.
+    required: true
+    type: string
+    format: string
+  - name: signature
+    in: query
+    description: signature authentifiant l'utilisateur comme étant authorisé à faire des requêtes à l'API (voir "calcul de la signature" pour plus d'informations sur le comment du calcul).
+    required: true
+    type: string
+    format: string
+tags:
+  - Companies
+responses:
+  '200':
+    description: Un tableau d'établissements
+    schema:
+      type: array
+      items:
+        $ref:
+          '#/definitions/Etablissement'
+  '400':
+    description: bad api request
+

labonneboite/web/api/swagger/conf.py

@@ -0,0 +1,38 @@
+template = {
+  "swagger": "2.0",
+  "info": {
+    "title": "API - La Bonne Boite",
+    "description": 'Trouvez les entreprises qui embauchent sans deposer d\'offres d\'emploi !',
+    "contact": {
+      "email": "[email protected]",
+      "url": "labonneboite.pole-emploi.fr",
+    },
+    "termsOfService": "https://labonneboite.pole-emploi.fr/conditions-generales",
+    "version": "1.0.0"
+  },
+  "host": "https://api.emploi-store.fr/partenaire/",  # overrides localhost:500
+  "basePath": "api",  # base bash for blueprint registration
+  "schemes": [
+    "http",
+    "https"
+  ],
+  "produces": [
+    "application/json",
+  ]
+}
+
+config = {
+    "headers": [
+    ],
+    "specs": [
+        {
+            "endpoint": 'apispec_1',
+            "route": '/apispec_1.json',
+            "rule_filter": lambda rule: True,  # all in
+            "model_filter": lambda tag: True,  # all in
+        }
+    ],
+    "swagger_ui": True,
+    "static_url_path": "/flasgger_static",
+    "specs_route": "/apidocs/"
+}

labonneboite/web/api/views.py

@@ -3,6 +3,7 @@
 from functools import wraps
 
 from flask import abort, Blueprint, current_app, jsonify, request
+from flasgger import swag_from
 
 from labonneboite.common import geocoding
 from labonneboite.common import search
@@ -58,8 +59,8 @@ def decorated(*args, **kwargs):
 
 # Note: `company` should be renamed to `office` wherever possible.
 # Unfortunately old routes cannot change.
-
 @apiBlueprint.route('/company/', methods=['GET'])
+@swag_from('./swagger/company.yml')
 @api_auth_required
 def company_list():
 
@@ -100,6 +101,7 @@ def company_list():
 
 
 @apiBlueprint.route('/filter/', methods=['GET'])
+@swag_from('./swagger/filter.yml')
 @api_auth_required
 def company_filter_list():
     current_app.logger.debug("API request received: %s", request.full_path)
@@ -280,6 +282,7 @@ def create_fetcher(location, request_args):
     return search.Fetcher(location, **kwargs)
 
 @apiBlueprint.route('/office/<siret>/details', methods=['GET'])
+@swag_from('./swagger/office_siret_detail.yml')
 @api_auth_required
 def office_details(siret):
     """

labonneboite/web/app.py

@@ -12,6 +12,7 @@
 from social_core.exceptions import AuthCanceled, AuthException, AuthFailed, AuthStateMissing
 from social_flask_sqlalchemy.models import init_social
 from werkzeug.contrib.fixers import ProxyFix
+from flasgger import Swagger
 import logstash
 
 # Flask.
@@ -31,6 +32,8 @@
 from labonneboite.common.models import User
 from labonneboite.common.models import Office
 from labonneboite.conf import settings
+from labonneboite.web.api.swagger.conf import config as swagger_config
+from labonneboite.web.api.swagger.conf import template as swagger_template
 
 # labonneboite web.
 from labonneboite.web.config import get_config
@@ -101,6 +104,7 @@ def register_extensions(flask_app):
     mandrill.init_app(flask_app)
     flask_app.extensions['mandrill'] = mandrill  # Provide easy access to the mandrill extension in Blueprints.
     login_manager.init_app(flask_app)
+    Swagger(flask_app, template=swagger_template, config=swagger_config)
     init_social(flask_app, db_session)
 
 

requirements.txt

@@ -75,6 +75,8 @@ gnureadline==6.3.3
 python-slugify==1.2.4
 requests==2.18.1
 validators==0.11.2
+flasgger==0.8.0
+
 
 # Pillow
 # For now, stick to Pillow 2.9 because later releases for Ubuntu 14.04 requires extra packages.