pyopenapi

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.

pyopenapi 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.

Read the Document, or just go through this README.

• Features
• Tutorial
• Quick Start
• Installation
• Reference
• Contributors
• Contribution Guideline
• FAQ
• Changes

---

Features

• NEW 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 pyopenapi. 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 pyopenapi.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
• Making a Request
• Access the Response
• Testing a Local Server
• Converting Document into another version
• Exntending Primitive Factory for user-defined primitives
• Rendering Random Requests for BlackBox Testing
• Operation MIME Support
• Test with Invalid Input
• Load Spec from a Restricted Service
• Customized Headers

---

Quick Start

Before running this script, please make sure requests is installed on your environment.

from pyopenapi import App, Security
from pyopenapi.contrib.client.requests import Client
from pyopenapi.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
pet = client.request(app.op['getPetById'](petId=1)).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
pet = client.request(app.resolve(jp_compose('/pet/{petId}', base='#/paths')).get(petId=1)).data
assert pet.id == 1

---

Installation

We support pip installtion.

pip install pyopenapi

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
• SwaggerClient
• Security

---

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

import logging
logger = logging.getLogger('pyopenapi')

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

request a merge

• try not to decrease the coverage rate
• test included

env preparation

pip install -r requirement-dev.txt

unit testing

python -m pytest -s -v --cov=pyopenapi --cov-config=.coveragerc pyopenapi/tests

---

FAQ

• Format of byte?
  • The way to encode/decode byte is base64.
• Format of datetime on the wire?
  • should be an ISO8601 string, according to this issue.
• How allowMultiple is handled?
  • Take type integer as example, you can pass an integer or an array/tuple of integer for this parameter. (a single value is no longer supported)
• What do we need to take care of when upgrading from Swagger 1.2 to 2.0?
  • allowMultiple is no longer supported, always passing an array even with a single value.
  • 'different host for different resource' is no longer supported in Swagger 2.0, only one host and one basePath is allowed in one swagger.json.
  • refer to Migration Guide from Swagger team.
  • The name of body parameters is no longer included in requests, refer to this issue for details.