8000 Add documentation · Pix4D/python-openapi-codec@b2547ae · GitHub
[go: up one dir, main page]
Skip to content
8000

Commit b2547ae

Browse files
tomchristietomchristie
committed
Add documentation
1 parent d74d456 commit b2547ae

File tree

1 file changed

+99
-0
lines changed

1 file changed

+99
-0
lines changed

‎README.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,113 @@
55
[![travis-image]][travis]
66
[![pypi-image]][pypi]
77

8+
## Introduction
9+
10+
This is a Python [Core API][coreapi] codec for the [Open API][openapi] schema format, also known as "Swagger".
11+
812
## Installation
913

1014
Install using pip:
1115

1216
$ pip install openapi-codec
1317

18+
## Creating Swagger schemas
19+
20+
To create a swagger schema from a `coreapi.Document`, use the codec directly.
21+
22+
>>> from openapi_codec import OpenAPICodec
23+
>>> codec = OpenAPICodec()
24+
>>> schema = codec.encode(document)
25+
26+
## Using with the Python Client Library
27+
28+
To use the Python client library to interact with a service that exposes a Swagger schema,
29+
include the codec in [the `decoders` argument][decoders].
30+
31+
>>> from openapi_codec import OpenAPICodec
32+
>>> from coreapi.codecs import JSONCodec
33+
>>> from coreapi import Client
34+
>>> decoders = [OpenAPICodec(), JSONCodec()]
35+
>>> client = Client(decoders=decoders)
36+
37+
If the server exposes the schema without properly using an `application/openapi+json` content type, then you'll need to make sure to include `format='openapi'` on the initial request,
38+
to force the correct codec to be used.
39+
40+
>>> schema = client.get('http://petstore.swagger.io/v2/swagger.json', format='openapi')
41+
42+
At this point you can now start to interact with the API:
43+
44+
>>> client.action(schema, ['pet', 'addPet'], params={'photoUrls': [], 'name': 'fluffy'})
45+
46+
## Using with the Command Line Client
47+
48+
Once the `openapi-codec` package is installed, the codec will automatically become available to the command line client.
49+
50+
$ pip install coreapi-cli openapi-codec
51+
$ coreapi codecs show
52+
Codec name Media type Support Package
53+
corejson | application/coreapi+json | encoding, decoding | coreapi==2.0.7
54+
openapi | application/openapi+json | encoding, decoding | openapi-codec==1.1.0
55+
json | application/json | decoding | coreapi==2.0.7
56+
text | text/* | decoding | coreapi==2.0.7
57+
download | */* | decoding | coreapi==2.0.7
58+
59+
If the server exposes the schema without properly using an `application/openapi+json` content type, then you'll need to make sure to include `format=openapi` on the initial request, to force the correct codec to be used.
60+
61+
$ coreapi get http://petstore.swagger.io/v2/swagger.json --format openapi
62+
<Swagger Petstore "http://petstore.swagger.io/v2/swagger.json">
63+
pet: {
64+
addPet(photoUrls, name, [status], [id], [category], [tags])
65+
deletePet(petId, [api_key])
66+
findPetsByStatus(status)
67+
...
68+
69+
At this point you can start to interact with the API.
70+
71+
$ coreapi action pet addPet --param name=fluffy --param photoUrls=[]
72+
{
73+
"id": 201609262739,
74+
"name": "fluffy",
75+
"photoUrls": [],
76+
"tags": []
77+
}
78+
79+
Use the `--debug` flag to see the full HTTP request and response.
80+
81+
$ coreapi action pet addPet --param name=fluffy --param photoUrls=[] --debug
82+
> POST /v2/pet HTTP/1.1
83+
> Accept-Encoding: gzip, deflate
84+
> Connection: keep-alive
85+
> Content-Length: 35
86+
> Content-Type: application/json
87+
> Accept: application/coreapi+json, */*
88+
> Host: petstore.swagger.io
89+
> User-Agent: coreapi
90+
>
91+
> {"photoUrls": [], "name": "fluffy"}
92+
< 200 OK
93+
< Access-Control-Allow-Headers: Content-Type, api_key, Authorization
94+
< Access-Control-Allow-Methods: GET, POST, DELETE, PUT
95+
< Access-Control-Allow-Origin: *
96+
< Connection: close
97+
< Content-Type: application/json
98+
< Date: Mon, 26 Sep 2016 13:17:33 GMT
99+
< Server: Jetty(9.2.9.v20150224)
100+
<
101+
< {"id":201609262739,"name":"fluffy","photoUrls":[],"tags":[]}
102+
103+
{
104+
"id": 201609262739,
105+
"name": "fluffy",
106+
"photoUrls": [],
107+
"tags": []
108+
}
14109

15110
[travis-image]: https://secure.travis-ci.org/core-api/python-openapi-codec.svg?branch=master
16111
[travis]: http://travis-ci.org/core-api/python-openapi-codec?branch=master
17112
[pypi-image]: https://img.shields.io/pypi/v/openapi-codec.svg
18113
[pypi]: https://pypi.python.org/pypi/openapi-codec
114+
115+
[coreapi]: http://www.coreapi.org/
116+
[openapi]: https://openapis.org/
117+
[decoders]: http://core-api.github.io/python-client/api-guide/client/#instantiating-a-client

0 commit comments

Comments
 (0)
0