swagger

El repo cuenta con documentacion semi automatica hecha con la libreria flasgger, se usa las extensiones FlaskPlugin y MarshmallowPlugin. Para ver la doc entrar a la ruta /activities/apidocs/

En la funcion swagger.init_swagger se agrega todos los schemas de marshmallow que queremos usar para documentar.

Ejemplo de como documentar una api

def post(self):
    """ Descripcion de la api
    ---
    security:
        - Bearer: []
    tags:
        - WorkOrder
    consumes:
    - application/json
    parameters:
    -   in: body
        name: body
        required: true
        schema:
            $ref: '#/definitions/WorkOrder'
    responses:
        200:
            schema:
                type: object
                properties:
                    work_order:
                        $ref: '#/definitions/WorkOrderReturn'
    """

security: - Bearer: []: especifico que la ruta require bearer token, se puede poner el token para probar las apis desde swagger (mejoras investigar como setear por defecto esto ya que todas las apis requieren login)
tags: etiqueta para agrupar las apis
$ref: el eschema tiene que estar agregado en Swagger, si el nombre termina en Schema no se agrega, ejemplo el eschema que tenemos en la doc de arriba es WorkOrderReturn pero la clase se llama WorkOrderReturnSchema
parameters: Pude definir los parametros con un schema de marshmallow si se pasa por body, para query_string los tengo que definir de a uno ejemplo:

def get(self):
    """Listar ordenes de trabajo
        ---
        security:
            - Bearer: []
        tags:
            - WorkOrder
        parameters:
            -   name: yeargroup
                in: query
                required: true
                type: int
            -   name: farm_id
                in: query
                type: int
    """

swagger​

swagger