Skip to content

Commit 32afbfc

Browse files
handrewshandrews
committed
Rewrite README, add tutorial files and INSTALL.md
Split installation details into their own file. Less rambling philosophy and more examples pasted directly from shell sessions. Add more API descriptions to the tutorial The infamous petstore.yaml, plus a multi-file description to show referencing as well as example validation including support for OAS 3.0-specific JSON Schema keywords.
1 parent f390e2b commit 32afbfc

File tree

9 files changed

+459
-275
lines changed

9 files changed

+459
-275
lines changed

‎INSTALL.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Installing pre-release `oascomply`
2+
3+
`oascomply` requires Python 3.8 or later, and has primarily been tested with 3.8.
4+
5+
Currently, `oascomply` must be checked out from GitHub and installed using
6+
the Python dependency management tool `poetry`. Publication to PyPI
7+
and support for installation with `pip` will be part of Milestone 4.
8+
9+
## Installing Python
10+
11+
`oascomply` requires Python 3.8 or later. Python.org provides installation
12+
instructions for [Windows](https://docs.python.org/3.11/using/windows.html)
13+
(through either the Python site or the
14+
[Microsoft Store](https://devblogs.microsoft.com/python/python-in-the-windows-10-may-2019-update/))
15+
and [Mac OS](https://docs.python.org/3.11/using/mac.html)
16+
(through the Python site).
17+
18+
If your system has an older version of Python, you can use
19+
[`pyenv`](https://github.com/pyenv/pyenv/blob/master/README.md),
20+
[`pyenv` for Windows](https://github.com/pyenv-win/pyenv-win/blob/master/README.md),
21+
or another similar tool to install an appropriate version.
22+
23+
_Note: At this stage, `oascomply` has only been tested with Python 3.8 on
24+
Mac OS 12.6 on an Apple M1 chip. Automated testing across Python 3.8-3.12
25+
will be added prior to publication. No support for earlier Python versions
26+
will be added due to the requirements of various dependencies. Please
27+
contact the maintainer if you can help with Windows testing._
28+
29+
## Installing `oascomply` from GitHub with `poetry`
30+
31+
`oascomply` is expected to be `pip`-installable by October 2023.
32+
Currently, it must be checked out from GitHub and installed
33+
using [`poetry`](https://python-poetry.org/docs/).
34+
35+
```ShellSession
36+
src % curl -sSL https://install.python-poetry.org | python3 -
37+
src % git clone https://github.com//OAI/oascomply.git
38+
src % cd oascomply
39+
oascomply % poetry install
40+
```
41+
42+
This keeps all of the `oascomply` dependencies in their own environment,
43+
which you can access with
44+
[`poetry shell`](https://python-poetry.org/docs/cli/#shell). Alternatively,
45+
you can prefix each command that you want to run with
46+
[`poetry run`](https://python-poetry.org/docs/cli/#run), e.g.:
47+
48+
```ShellSession
49+
oascomply % poetry run python oascomply -h
50+
```
51+
52+
Note that all `poetry` commands need to be run from inside
53+
the repository directory, as `poetry` determines what environment
54+
to use by looking in the current directory and its parent
55+
directories for a `pyproject.toml` file. Otherwise you will
56+
see an error like this:
57+
58+
```ShellSession
59+
src % poetry run python oascomply -h
60+
61+
Poetry could not find a pyproject.toml file in /Users/someone/src or its parents
62+
```
63+

‎README.md

+219-275
Large diffs are not rendered by default.

‎descriptions/README.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
The descriptions here are not guaranteed to be valid, and will either be removed or moved over to the tutorial directory.
2+
3+
The GitHub JSON file takes a good two minutes to validate on the author's laptop, and will only pass validation if example validation is disabled with `-e false`. The YAML version is exceedingly slow.

‎tutorial/minimal.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "Minimal OAS 3.0 description",
5+
"version": "1.0.0"
6+
},
7+
"paths": {
8+
}
9+
}

‎tutorial/minimal.png

510 KB
Loading

‎tutorial/petstore.yaml

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
openapi: "3.0.0"
2+
info:
3+
version: 1.0.0
4+
title: Swagger Petstore
5+
license:
6+
name: MIT
7+
servers:
8+
- url: http://petstore.swagger.io/v1
9+
paths:
10+
/pets:
11+
get:
12+
summary: List all pets
13+
operationId: listPets
14+
tags:
15+
- pets
16+
parameters:
17+
- name: limit
18+
in: query
19+
description: How many items to return at one time (max 100)
20+
required: false
21+
schema:
22+
type: integer
23+
maximum: 100
24+
format: int32
25+
responses:
26+
'200':
27+
description: A paged array of pets
28+
headers:
29+
x-next:
30+
description: A link to the next page of responses
31+
schema:
32+
type: string
33+
content:
34+
application/json:
35+
schema:
36+
$ref: "#/components/schemas/Pets"
37+
default:
38+
description: unexpected error
39+
content:
40+
application/json:
41+
schema:
42+
$ref: "#/components/schemas/Error"
43+
post:
44+
summary: Create a pet
45+
operationId: createPets
46+
tags:
47+
- pets
48+
responses:
49+
'201':
50+
description: Null response
51+
default:
52+
description: unexpected error
53+
content:
54+
application/json:
55+
schema:
56+
$ref: "#/components/schemas/Error"
57+
/pets/{petId}:
58+
get:
59+
summary: Info for a specific pet
60+
operationId: showPetById
61+
tags:
62+
- pets
63+
parameters:
64+
- name: petId
65+
in: path
66+
required: true
67+
description: The id of the pet to retrieve
68+
schema:
69+
type: string
70+
responses:
71+
'200':
72+
description: Expected response to a valid request
73+
content:
74+
application/json:
75+
schema:
76+
$ref: "#/components/schemas/Pet"
77+
default:
78+
description: unexpected error
79+
content:
80+
application/json:
81+
schema:
82+
$ref: "#/components/schemas/Error"
83+
components:
84+
schemas:
85+
Pet:
86+
type: object
87+
required:
88+
- id
89+
- name
90+
properties:
91+
id:
92+
type: integer
93+
format: int64
94+
name:
95+
type: string
96+
tag:
97+
type: string
98+
Pets:
99+
type: array
100+
maxItems: 100
101+
items:
102+
$ref: "#/components/schemas/Pet"
103+
Error:
104+
type: object
105+
required:
106+
- code
107+
- message
108+
properties:
109+
code:
110+
type: integer
111+
format: int32
112+
message:
113+
type: string

‎tutorial/references/openapi.json

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
"openapi": "3.0.3",
3+
"info": {
4+
"title": "Basic referencing",
5+
"version": "1.0.0"
6+
},
7+
"paths": {
8+
"/foo": {
9+
"$ref": "pathitems/foo"
10+
}
11+
},
12+
"components": {
13+
"responses": {
14+
"foo": {
15+
"description": "OK",
16+
"content": {
17+
"application/json": {
18+
"schema": {
19+
"$ref": "#/components/schemas/bar"
20+
},
21+
"example": "one"
22+
}
23+
},
24+
"links": {
25+
"self": {
26+
"operationRef": "pathitems/foo#/get"
27+
}
28+
}
29+
}
30+
},
31+
"schemas": {
32+
"bar": {
33+
"$ref": "schemas/bar#"
34+
}
35+
}
36+
}
37+
}

‎tutorial/references/pathitems/foo.json

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{
2+
"get": {
3+
"responses": {
4+
"200": {
5+
"$ref": "../openapi#/components/responses/foo"
6+
}
7+
}
8+
}
9+
}

‎tutorial/references/schemas/bar.json

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"type": "string",
3+
"nullable": true,
4+
"example": null,
5+
"default": "four"
6+
}

0 commit comments

Comments
 (0)