Skip to content

Commit ab0fb74

Browse files
p1c2up1c2u
authored
Merge pull request #68 from p1c2u/feature/documentation-improvements
documentation improvements
2 parents c35b702 + a1238f9 commit ab0fb74

13 files changed

+1154
-178
lines changed

Diff for: ‎.github/workflows/build-docs.yml

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: Build documentation
2+
3+
on:
4+
push:
5+
pull_request:
6+
types: [opened, synchronize]
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v2
13+
14+
- name: Set up Python 3.9
15+
uses: actions/setup-python@v2
16+
with:
17+
python-version: 3.9
18+
19+
- name: Get full Python version
20+
id: full-python-version
21+
run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
22+
23+
- name: Bootstrap poetry
24+
run: |
25+
curl -sL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python - -y
26+
echo "$HOME/.local/bin" >> $GITHUB_PATH
27+
28+
- name: Configure poetry
29+
run: poetry config virtualenvs.in-project true
30+
31+
- name: Set up cache
32+
uses: actions/cache@v2
33+
id: cache
34+
with:
35+
path: .venv
36+
key: venv-${{ steps.full-python-version.outputs.version }}-${{ hashFiles('**/poetry.lock') }}
37+
38+
- name: Ensure cache is healthy
39+
if: steps.cache.outputs.cache-hit == 'true'
40+
run: timeout 10s poetry run pip --version || rm -rf .venv
41+
42+
- name: Install dependencies
43+
run: poetry install -E docs
44+
45+
- name: Build documentation
46+
run: |
47+
poetry run python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs docs/_build/html -n -W
48+
49+
- uses: actions/upload-artifact@v2
50+
name: Upload docs as artifact
51+
with:
52+
name: docs-html
53+
path: './docs/_build/html'
54+
if-no-files-found: error

Diff for: ‎.readthedocs.yaml

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: 2
2+
3+
sphinx:
4+
configuration: docs/conf.py
5+
6+
formats: all
7+
8+
python:
9+
version: 3.8
10+
install:
11+
- method: pip
12+
path: .
13+
extra_requirements:
14+
- docs

Diff for: ‎CONTRIBUTING.rst

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Please read the `Contributing <https://openapi-schema-validator.readthedocs.io/en/latest/contributing.html>`__ guidelines in the documentation site.

Diff for: ‎README.rst

+13-150
Original file line numberDiff line numberDiff line change
@@ -23,27 +23,32 @@ Openapi-schema-validator is a Python library that validates schema against:
2323
* `OpenAPI Schema Specification v3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject>`__ which is an extended subset of the `JSON Schema Specification Wright Draft 00 <http://json-schema.org/>`__.
2424
* `OpenAPI Schema Specification v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schemaObject>`__ which is an extended superset of the `JSON Schema Specification Draft 2020-12 <http://json-schema.org/>`__.
2525

26+
27+
Documentation
28+
#############
29+
30+
Check documentation to see more details about the features. All documentation is in the "docs" directory and online at `openapi-schema-validator.readthedocs.io <https://openapi-schema-validator.readthedocs.io>`__
31+
32+
2633
Installation
2734
############
2835

2936
Recommended way (via pip):
3037

31-
::
38+
.. code-block:: console
3239
33-
$ pip install openapi-schema-validator
40+
pip install openapi-schema-validator
3441
3542
Alternatively you can download the code and install from the repository:
3643

37-
.. code-block:: bash
44+
.. code-block:: console
3845
39-
$ pip install -e git+https://github.com/p1c2u/openapi-schema-validator.git#egg=openapi_schema_validator
46+
pip install -e git+https://github.com/p1c2u/openapi-schema-validator.git#egg=openapi_schema_validator
4047
4148
4249
Usage
4350
#####
4451

45-
By default, the latest OpenAPI schema syntax is expected.
46-
4752
To validate an OpenAPI v3.1 schema:
4853

4954
.. code-block:: python
@@ -92,151 +97,9 @@ To validate an OpenAPI v3.1 schema:
9297
...
9398
ValidationError: Additional properties are not allowed ('city' was unexpected)
9499
95-
if you want to disambiguate the expected schema version, import and use ``OAS31Validator``:
96-
97-
.. code-block:: python
98-
99-
from openapi_schema_validator import OAS31Validator
100-
101-
validate({"name": "John", "age": 23}, schema, cls=OAS31Validator)
102-
103-
In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` instead of ``OAS31Validator``.
104-
105-
.. code-block:: python
106-
107-
from openapi_schema_validator import OAS30Validator
108-
109-
# A sample schema
110-
schema = {
111-
"type": "object",
112-
"required": [
113-
"name"
114-
],
115-
"properties": {
116-
"name": {
117-
"type": "string"
118-
},
119-
"age": {
120-
"type": "integer",
121-
"format": "int32",
122-
"minimum": 0,
123-
"nullable": True,
124-
},
125-
"birth-date": {
126-
"type": "string",
127-
"format": "date",
128-
}
129-
},
130-
"additionalProperties": False,
131-
}
132-
133-
validate({"name": "John", "age": None}, schema, cls=OAS30Validator)
134-
135-
In order to validate read/write context in OpenAPI 3.0 schema, import and use ``OAS30ReadValidator`` or ``OAS30WriteValidator``.
136-
137-
.. code-block:: python
138-
139-
from openapi_schema_validator import OAS30WriteValidator
140-
141-
# A sample schema
142-
schema = {
143-
"type": "object",
144-
"required": [
145-
"name"
146-
],
147-
"properties": {
148-
"name": {
149-
"type": "string"
150-
},
151-
"age": {
152-
"type": "integer",
153-
"format": "int32",
154-
"minimum": 0,
155-
"readOnly": True,
156-
},
157-
"birth-date": {
158-
"type": "string",
159-
"format": "date",
160-
}
161-
},
162-
"additionalProperties": False,
163-
}
164-
165-
validate({"name": "John", "age": 23}, schema, cls=OAS30WriteValidator)
166-
167-
Traceback (most recent call last):
168-
...
169-
ValidationError: Tried to write read-only property with 23
170-
171-
Format check
172-
************
173-
174-
You can also check format for primitive types
175-
176-
.. code-block:: python
177-
178-
from openapi_schema_validator import oas31_format_checker
179-
180-
validate({"name": "John", "birth-date": "-12"}, schema, format_checker=oas31_format_checker)
181-
182-
Traceback (most recent call last):
183-
...
184-
ValidationError: '-12' is not a 'date'
185-
186-
References
187-
**********
188-
189-
You can resolve JSON references by passing custon reference resolver
190-
191-
.. code-block:: python
192-
193-
from jsonschema.validators import RefResolver
194-
195-
# A schema with reference
196-
schema = {
197-
"type" : "object",
198-
"required": [
199-
"name"
200-
],
201-
"properties": {
202-
"name": {
203-
"$ref": "#/components/schemas/Name"
204-
},
205-
"age": {
206-
"$ref": "#/components/schemas/Age"
207-
},
208-
"birth-date": {
209-
"$ref": "#/components/schemas/BirthDate"
210-
}
211-
},
212-
"additionalProperties": False,
213-
}
214-
# Referenced schemas
215-
schemas = {
216-
"components": {
217-
"schemas": {
218-
"Name": {
219-
"type": "string"
220-
},
221-
"Age": {
222-
"type": "integer",
223-
"format": "int32",
224-
"minimum": 0,
225-
"nullable": True,
226-
},
227-
"BirthDate": {
228-
"type": "string",
229-
"format": "date",
230-
}
231-
},
232-
},
233-
}
234-
235-
ref_resolver = RefResolver.from_schema(schemas)
236-
237-
validate({"name": "John", "age": 23}, schema, resolver=ref_resolver)
100+
By default, the latest OpenAPI schema syntax is expected.
238101

239-
For more information about reference resolver see `Resolving JSON References <https://python-jsonschema.readthedocs.io/en/stable/references/>`__
102+
For more details read about `Validation <https://openapi-schema-validator.readthedocs.io/en/latest/validation.html>`__.
240103

241104
Related projects
242105
################

Diff for: ‎docs/conf.py

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import openapi_schema_validator
2+
3+
project = "openapi-schema-validator"
4+
copyright = "2023, Artur Maciag"
5+
author = "Artur Maciag"
6+
7+
release = openapi_schema_validator.__version__
8+
9+
extensions = [
10+
"sphinx.ext.autodoc",
11+
"sphinx.ext.doctest",
12+
"sphinx.ext.intersphinx",
13+
"sphinx.ext.coverage",
14+
"sphinx.ext.viewcode",
15+
"sphinx_immaterial",
16+
]
17+
18+
templates_path = ["_templates"]
19+
20+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
21+
22+
html_theme = "sphinx_immaterial"
23+
24+
html_static_path = []
25+
26+
html_title = "openapi-schema-validator"
27+
28+
html_theme_options = {
29+
"analytics": {
30+
"provider": "google",
31+
"property": "G-11RDPBZ7EJ",
32+
},
33+
"repo_url": "https://github.com/p1c2u/openapi-schema-validator/",
34+
"repo_name": "openapi-schema-validator",
35+
"repo_type": "github",
36+
"icon": {
37+
"repo": "fontawesome/brands/github-alt",
38+
"edit": "material/file-edit-outline",
39+
},
40+
"palette": [
41+
{
42+
"media": "(prefers-color-scheme: dark)",
43+
"scheme": "slate",
44+
"primary": "lime",
45+
"accent": "amber",
46+
"scheme": "slate",
47+
"toggle": {
48+
"icon": "material/toggle-switch",
49+
"name": "Switch to light mode",
50+
},
51+
},
52+
{
53+
"media": "(prefers-color-scheme: light)",
54+
"scheme": "default",
55+
"primary": "lime",
56+
"accent": "amber",
57+
"toggle": {
58+
"icon": "material/toggle-switch-off-outline",
59+
"name": "Switch to dark mode",
60+
},
61+
},
62+
],
63+
"globaltoc_collapse": False,
64+
}

0 commit comments

Comments
 (0)