abatilo / sanic-swagger

Easily document your Sanic API with a UI (and attrs!)

sanic-swagger

Annotate your Sanic endpoints, and automatically generate a Swagger/OpenAPI compatible JSON spec file.

This project is a fork of both sanic-openapi and sanic-attrs.

As such, you can write all of your models as attrs which gives you the handy ability to use cattrs for dealing with your serialization and deserialization of your models to and from JSON.

sanic-swagger's Issues

Create templates for new issue and prs

To help streamline the Issue/PR process, we need to add templates to the repo.

Consuming header does not produce the correct swagger documentation

Subject of the issue

Hi all, I create this issue here because this project looks more active then sanic-openapi.
I'm trying to document a route that it's consuming a header but it generates a body as parameter in the swagger documentation.

Steps to reproduce

I have written this:
@doc.consumes(AuthorizationHeaderDoc, location="header", content_type="application/x-www-form-urlencoded")

With the class:

class AuthorizationHeaderDoc(doc.Model):
          authorization = doc.field(type=str, description="Authorization key.")

Expected behaviour

What I would like to have in the swagger documentation is:

Actual behaviour

But I get this instead:

Is there no support for documenting headers or am I doing something wrong? Any help would be appreciated! Thanks!

Define contributing guidelines

We need to decide what the requirements are for people to contribute.

Add testing/build steps to the README

Every time we receive a PR, we run the following steps:

sanic-swagger/.circleci/config.yml

Lines 3 to 31 in ca16ca4

	lint_git_commits:
	docker:
	- image: python:3.6
	working_directory: ~/sanic-swagger
	steps:
	- checkout
	- run: pip install gitlint
	- run: gitlint --commits fbb925a...HEAD
	lint:
	docker:
	- image: python:3.6
	working_directory: ~/sanic-swagger
	steps:
	- checkout
	- run: pip install pipenv
	- run: pipenv install --dev
	- run: pipenv run flake8 --show-source --import-order-style pep8
	test:
	docker:
	- image: python:3.6
	working_directory: ~/sanic-swagger
	steps:
	- checkout
	- run: pip install pipenv
	- run: pipenv install --dev
	- run: pipenv run pytest --cov-report html --cov-report xml:codecov.xml --junit-xml=coverage.xml --cov-branch --cov-fail-under=90 -v --cov=sanic_swagger tests/
	- run: mkdir -p test-results/pytest && cp coverage.xml test-results/pytest/results.xml

It would be extremely useful to have sections in the README for how to run these locally, so that people who want to contribute, can make sure that all of these steps will pass locally, before pushing the PR.

Need Documentation

Require documentation to use

It would be nice to have some initial documentation that would help to get started with the basic swagger document.

Since this is derived from sanic-openapi and sanic-attrs, can we have parts of their documentation that remain the same to at least bootstrap with the basic configurations?

Setup tox for testing against multiple versions of python

Right now, we claim to be compatible with python 3.5, 3.6, and 3.7. We already know that we break on Python 3.7.

We're only currently running tests using Python 3.6, so we should add a tox config so that we can run tests using multiple different versions of Python, to help ensure that we maintain compatibility across all versions that we claim to support.

Support Python 3.7

Subject of the issue

Types in Python 3.7 fail to pass the tests that we currently have. This somewhat relates to #12

Steps to reproduce

Switch the python version that's defined in the Pipfile, to use Python 3.7, and then try to run our tests

Expected behaviour

All of the tests should pass

Actual behaviour

5 tests fail under Python 3.7