pyswagger

An OpenAPI (fka Swagger) client & converter in python, which is type-safe, dynamic, spec-compliant.

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.

Programming language: Python

License: MIT License

Tags: RESTful API     Utilities     Python     OpenAPI     Swagger    

Latest version: v0.8.39

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
  • requests
  • tornado.httpclient.AsyncHTTPClient
  • flask.testing.FlaskClient
  • webapp2
• 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

• Marcin Goliński
• Andrey Mikhailov
• Telepenin Nikolay
• WangJiannan

---

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