Metadata-Version: 2.1
Name: flask-redoc
Version: 0.2.1
Summary: UNKNOWN
Home-page: https://github.com/mzaglia/flask-redoc
Author: Matheus C. Zaglia
Author-email: mzaglia@gmail.com
License: MIT
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
Requires-Dist: Flask (>=1.1.1)
Requires-Dist: PyYAML (>=5.3)
Requires-Dist: apispec (>=3.3.1)
Requires-Dist: apispec-webframeworks (>=0.5.2)
Requires-Dist: jsonmerge (>=1.7.0)
Requires-Dist: marshmallow (>=3.6.1)
Provides-Extra: all
Requires-Dist: Sphinx (>=2.2) ; extra == 'all'
Requires-Dist: coverage (>=4.5) ; extra == 'all'
Requires-Dist: coveralls (>=1.8) ; extra == 'all'
Requires-Dist: pytest (>=5.2) ; extra == 'all'
Requires-Dist: pytest-cov (>=2.8) ; extra == 'all'
Requires-Dist: pytest-pep8 (>=1.0) ; extra == 'all'
Requires-Dist: pydocstyle (>=4.0) ; extra == 'all'
Requires-Dist: isort (>4.3) ; extra == 'all'
Requires-Dist: check-manifest (>=0.40) ; extra == 'all'
Provides-Extra: docs
Requires-Dist: Sphinx (>=2.2) ; extra == 'docs'
Provides-Extra: tests
Requires-Dist: coverage (>=4.5) ; extra == 'tests'
Requires-Dist: coveralls (>=1.8) ; extra == 'tests'
Requires-Dist: pytest (>=5.2) ; extra == 'tests'
Requires-Dist: pytest-cov (>=2.8) ; extra == 'tests'
Requires-Dist: pytest-pep8 (>=1.0) ; extra == 'tests'
Requires-Dist: pydocstyle (>=4.0) ; extra == 'tests'
Requires-Dist: isort (>4.3) ; extra == 'tests'
Requires-Dist: check-manifest (>=0.40) ; extra == 'tests'

# flask-redoc
[![Build Status](https://travis-ci.com/mzaglia/flask-redoc.svg?branch=master)](https://travis-ci.com/mzaglia/flask-redoc)
[![Documentation Status](https://readthedocs.org/projects/flask-redoc/badge/?version=latest)](http://flask-redoc.readthedocs.io/?badge=latest)
[![GitHub license](https://img.shields.io/github/license/mzaglia/flask-redoc)](https://github.com/mzaglia/flask-redoc/blob/master/LICENSE)
[![GitHub tag](https://img.shields.io/github/tag/mzaglia/flask-redoc.svg)](https://github.com/mzaglia/flask-redoc/tags/)
[![PyPI version shields.io](https://img.shields.io/pypi/v/flask-redoc.svg)](https://pypi.python.org/pypi/flask-redoc/)


A Flask extension for displaying OpenAPI/Swagger documentation using Redocs.

# Installation
Under your virtualenv do:

```shell
pip install flask-redoc
```

or (dev version)

```shell
pip install https://github.com/mzaglia/flask-redoc
```

# Getting Started

## Using YAML file
Save your `petstore.yml`
```yaml
openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
```

Load in your app:
```python

from flask import Flask
from flask_redoc import Redoc

redoc = Redoc(app,'petstore.yml')

@app.route('/pets', methods=['GET', 'POST'])
def pets():
    ...
```

You can also use docstrings as specification and Marshmallow models for schemas (this will updated any existing specs loaded with YAML files).

```python

app.config['REDOC'] = {'title':'Petstore', 'marshmallow_schemas':[PetSchema]}

class PetSchema(Schema):
    name = fields.Str()

@app.route('/random')
def random():
    """A cute furry animal endpoint.
    ---
    get:
      description: Get a random pet
      responses:
        200:
          description: Return a pet
          content:
            application/json:
              schema: PetSchema
    """
    return PetSchema().dump(dict(name="Bird"))
```
# Configuration

## Default configuration
```python
 DEFAULT_CONFIG = {
        'endpoint': 'docs',
        'spec_route': '/docs',
        'static_url_path': '/redoc_static',
        'title': 'ReDoc',
        'version': '1.0.0',
        'openapi_version': '3.0.2',
        'info': dict(),
        'marshmallow_schemas': list()
    }
```

## Changing configuration
You can change any default configuration as follows
```python
app.config['REDOC'] = {'spec_route': '/my_docs', 'title': 'My Docs'}
redoc = Redoc(app)
```

# Further reading
For more information about creating your spec using docstring, please visit: https://apispec.readthedocs.io/en/latest/


