Quickstart¶
Specs¶
Loading¶
OpenAPI specifications are loaded using OpenApiObject
.
Specs can be loaded from an io
object, a file path, or a URI. Both
json
and yaml
files are supported.
First, get the thing imported:
>>> from poast.openapi3.spec import OpenApiObject
Then, load a spec (all of the following work):
>>> doc_from_url = OpenApiObject(
... 'https://petstore3.swagger.io/api/v3/openapi.json')
>>> doc_from_filepath = OpenApiObject('./my/openapi.yml')
>>> with open('./my/other/openapi.json', 'rb') as f:
>>> from_io = OpenApiObject(f)
Validation¶
Validation is performed using the validate()
method on the returned
OpenApiObject
, e.g.:
>>> my_doc = OpenApiObject('./path/to/my/openapi.yml')
>>> my_doc.validate()
- Loading or validation errors will raise
DocumentParsingException
. - Errors with the document itself, will raise
MalformedDocumentException
See also
poast.openapi3.spec.model.exceptions
Clients¶
Generating¶
Clients are created from a OpenApiObject
using get_client_cls()
function, e.g.:
>>> from poast.openapi3.spec import OpenApiObject
>>> from poast.openapi3.client import gen_client_cls
>>>
>>> # api_spec = OpenApiObject(...).validate()
>>>
>>> # Generate a client class from the spec:
>>> MyApiClient = gen_client_cls('MyApiClient', api_spec)
The return value is a subclass of OpenApiClient
,
objects of which can be instantiated in the usual fashion:
>>> client = MyApiClient('https://myservice.com/api/root')
API Operations¶
The client classes created using get_client_cls()
have
a special attribute, op
(an API-specific subclass of OpenApiOperations
),
with one method for each API operation
defined in the spec. For example, if an api describes two operations,
someAction
and anotherAction
, client instances will have the following
two methods in their op
object:
>>> client.op.someAction()
>>> client.op.anotherAction()
Invoking Operations¶
Methods defined on the OpenApiOperations
subclass generally mimic the
call signature of requests.Request()
, with path parameters passed as
keyword arguments.
Request Parameters¶
Spec "in" : |
Passed as: |
---|---|
path |
**kwargs |
query |
params (dict) |
header |
headers (dict) |
cookie |
cookies (dict) |
Request Body¶
The the request body
can passed - requests
-style as either
json
, data
, stream
, or files
.
Note
In the event that a path parameter collides with a Python keyword, builtin,
or existing named parameter to the underlying requests.Request
object method, both the URI template and the parameter name are adjusted to
include the suffix '_'
.
Example¶
Consider, for instance, a utility provider which provides a customer API.
Let’s suppose that the API provides a getUsage
operation which requires us
to make a GET
request with:
- a
customerId
parameter specified in the URI path- a
days
parameter, specified as a query arg- an auth token, in the
X-API-Key
HTTP header
Finding the resource usage for user #123 over the last 30 days might look like:
>>> resp = my_client.getUsage(
... customerId=123,
... params={'days': 30},
... headers{'X-API-KEY': MY_SECRET_API_KEY}
... ).execute()
The resp
object here is a standard requests.Response
object.
We can get the body as text like so:
>>> print(resp.text)
Or (if it’s JSON), like so:
>>> print(resp.json())
API Help¶
Operations for generated clients include docstrings for each method that indicates the type and location of all required parameters, e.g.:
>>> help(my_client.op.getPetById)
Help on method getPetById in module poast.openapi3.client.genop:
getPetById(headers=None, params=None, cookies=None, data=None, json=None, files=None, hooks=None, **path_params) method of poast.openapi3.client.genops.PoastExampleClientOperations instance
http: GET /pet/{petId}
summary: Find pet by ID
description: Returns a single pet
path parameters (keyword args):
petId:
description: ID of pet to return
required: True
deprecated: False
allowEmptyValue: False
Security Requirements:
api_key: []
petstore_auth: ['write:pets', 'read:pets']