Description
A python client for Swagger enabled REST API. It wouldn't be easier to
try Swagger REST API by Swagger-UI. However, when it's time to unittest
your API, the first option you find would be Swagger-codegen, but the better option is us.
This project is developed after swagger-py, which is a nicely implemented one, and inspired many aspects of this project. Another project is flex, which focuses on parameter validation, try it if you can handle other parts by yourselves. For other projects related to Swagger tools in python, check here.
pyswagger alternatives and similar packages
Based on the "RESTful API" category.
Alternatively, view pyswagger alternatives based on common mentions on social networks and blogs.
-
hug
A Python3 framework for cleanly exposing APIs over HTTP and the Command Line with automatic documentation and validation. -
connexion
Swagger/OpenAPI First framework for Python on top of Flask with automatic endpoint validation & OAuth2 support -
flasgger
Creates Swagger 2.0 API documentation for all your Flask views extracting specs from docstrings or referenced files -
apispec
A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification). -
Blueprint/Boilerplate For Python Projects
Blueprint/Boilerplate For Python Projects -
django-admin-interface
django-admin-interface is a customizable responsive admin interface, based on a modern flat theme, it lets you customize the admin title, logo and colors by the admin itself. Popup windows replaced by modals. -
bravado
Bravado is a Yelp maintained fork of digium/swagger-py for use with OpenAPI Specification version 2.0 -
django-maintenance-mode
django-maintenance-mode shows a 503 error page when maintenance mode is on. -
django-template
A flexible Django 1.4-1.9 project template with configurations for EC2, Heroku, App Engine, and Docker. -
Changelog CI
Changelog CI is a GitHub Action that generates changelog, prepends it to CHANGELOG.md file and commits it to a release pull request -
Cilantropy
Cilantropy is a Python Package Manager interface created to provide an "easy-to-use" visual and also a command-line interface for Pythonistas.
Get performance insights in less than 4 minutes
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest. Visit our partner's website for more details.
Do you think we are missing an alternative of pyswagger or a related project?
README
pyswagger
A python client for Swagger enabled REST API. It wouldn't be easier to try Swagger REST API by Swagger-UI. However, when it's time to unittest your API, the first option you find would be Swagger-codegen, but the better option is us.
This project is developed after swagger-py, which is a nicely implemented one, and inspired many aspects of this project. Another project is flex, which focuses on parameter validation, try it if you can handle other parts by yourselves. For other projects related to Swagger tools in python, check here.
pyswagger is much easier to use (compared to swagger-codegen, you don't need to prepare a scala environment) and tries hard to fully supports Swagger Spec in all aspects.
- [NEWs: upcoming support for OpenAPI 3.0](docs/md/news.md)
- [Features](README.md#features)
- [Tutorial](README.md#tutorial)
- [Quick Start](README.md#quick-start)
- [Installation](README.md#installation)
- [Reference](README.md#reference)
- [Contributors](README.md#contributors)
- [Contribution Guideline](README.md#contribution-guildeline)
- [FAQ](docs/md/faq.md)
- [Changes](CHANGES.md)
Features
- convert Swagger Document from older version to newer one. (ex. convert from 1.2 to 2.0)
- support Swagger 1.2, 2.0 on python
2.6, 2.7, 3.3, 3.5, 3.6 - support YAML via Pretty-YAML
- support $ref to External Document, multiple swagger.json will be organized into a group of App. And external document with self-describing resource is also supported (refer to issue).
- type safe, input/output are converted to python types according to Data Type described in Swagger. You don't need to touch any json schema when using pyswagger. Limitations like minimum/maximum or enum are also checked. Model inheritance also supported.
- provide function App.validate to check validity of the loaded API definition according to spec.
- builtin client implementation based on various http clients in python. For usage of these clients, please refer to
pyswagger.tests.contrib.client
for details - not implemented parts, fire me a bug if you need it
- [ ] Swagger 2.0
- [ ] Schema.pattern
- [ ] Scheme.patternProperties
- [ ] Schema.readonly
- [ ] Schema.allowEmptyValue
- [ ] A scanner to validate schema
- [ ] A WebSocket client
- [ ] dump extension field
Tutorial
- [Initialization](docs/md/tutorial/init.md)
- [Making a Request](docs/md/tutorial/request.md)
- [Access the Response](docs/md/tutorial/response.md)
- [Testing a Local Server](docs/md/tutorial/local.md)
- [Converting Document into another version](docs/md/tutorial/converter.md)
- [Exntending Primitive Factory for user-defined primitives](docs/md/tutorial/extend_prim.md)
- [Rendering Random Requests for BlackBox Testing](docs/md/tutorial/render.md)
- [Operation MIME Support](docs/md/tutorial/mime.md)
- [Test with Invalid Input](docs/md/tutorial/invalid.md)
- [Load Spec from a Restricted Service](docs/md/tutorial/restricted_service.md)
- [Customized Headers](docs/md/tutorial/customized_headers.md)
Quick Start
Before running this script, please make sure requests is installed on your environment.
from pyswagger import App, Security
from pyswagger.contrib.client.requests import Client
from pyswagger.utils import jp_compose
# load Swagger resource file into App object
app = App._create_('http://petstore.swagger.io/v2/swagger.json')
auth = Security(app)
auth.update_with('api_key', '12312312312312312313q') # api key
auth.update_with('petstore_auth', '12334546556521123fsfss') # oauth2
# init swagger client
client = Client(auth)
# a dict is enough for representing a Model in Swagger
pet_Tom=dict(id=1, name='Tom', photoUrls=['http://test'])
# a request to create a new pet
client.request(app.op['addPet'](body=pet_Tom))
# - access an Operation object via App.op when operationId is defined
# - a request to get the pet back
req, resp = app.op['getPetById'](petId=1)
# prefer json as response
req.produce('application/json')
pet = client.request((req, resp)).data
assert pet.id == 1
assert pet.name == 'Tom'
# new ways to get Operation object corresponding to 'getPetById'.
# 'jp_compose' stands for JSON-Pointer composition
req, resp = app.resolve(jp_compose('/pet/{petId}', base='#/paths')).get(petId=1)
req.produce('application/json')
pet = client.request((req, resp)).data
assert pet.id == 1
Installation
We support pip installtion.
pip install pyswagger
Additional dependencies must be prepared before firing a request. If you are going to access a remote/local web server, you must install requests first.
pip install requests
If you want to test a local tornado server, please make sure tornado is ready on your environment
pip install tornado
We also provide native client for flask app, but to use it, flask is also required
pip install flask
Reference
All exported API are described in following sections.
- [App](docs/md/ref/app.md)
- [SwaggerClient](docs/md/ref/client.md)
- [Security](docs/md/ref/security.md)
Contributors
Contribution Guildeline
report an issue:
- issues can be reported here
- include swagger.json if possible
- turn on logging and report with messages on console ```python import logging logger = logging.getLogger('pyswagger')
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
console = logging.StreamHandler() console.setLevel(logging.DEBUG) console.setFormatter(formatter)
logger.addHandler(console) logger.setLevel(logging.DEBUG)
... your stuff
- describe expected behavior, or more specific, the input/output
#### submit a PR
- test included
- only PR to `develop` would be accepted
env preparation
```bash
pip install -r requirement-dev.txt
unit testing
python -m pytest -s -v --cov=pyswagger --cov-config=.coveragerc pyswagger/tests