Skip to content

Commit ce94d74

Browse files
p1c2up1c2u
committed
documentation improvements
1 parent e798c5a commit ce94d74

14 files changed

+915
-68
lines changed

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

‎.github/workflows/python-test.yml

+2-4
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,8 @@ jobs:
2929
id: full-python-version
3030
run: echo ::set-output name=version::$(python -c "import sys; print('-'.join(str(v) for v in sys.version_info))")
3131

32-
- name: Bootstrap poetry
33-
run: |
34-
python -m pip install --upgrade pip
35-
pip install "poetry<1.2"
32+
- name: Set up poetry
33+
uses: Gr1N/setup-poetry@v8
3634

3735
- name: Configure poetry
3836
run: poetry config virtualenvs.in-project true

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

‎CONTRIBUTING.rst

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

‎README.rst

+27-55
Original file line numberDiff line numberDiff line change
@@ -25,54 +25,61 @@ against the `OpenAPI 2.0 (aka Swagger)
2525
and `OpenAPI 3.1 <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md>`__
2626
specification. The validator aims to check for full compliance with the Specification.
2727

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

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

3744
.. code-block:: bash
3845
39-
$ pip install -e git+https://github.com/p1c2u/openapi-spec-validator.git#egg=openapi_spec_validator
46+
pip install -e git+https://github.com/p1c2u/openapi-spec-validator.git#egg=openapi_spec_validator
4047
4148
4249
Usage
4350
#####
4451

45-
Command Line Interface
46-
**********************
52+
CLI (Command Line Interface)
53+
****************************
4754

4855
Straight forward way:
4956

50-
.. code:: bash
57+
.. code-block:: bash
5158
52-
$ openapi-spec-validator openapi.yaml
59+
openapi-spec-validator openapi.yaml
5360
5461
pipes way:
5562

56-
.. code:: bash
63+
.. code-block:: bash
5764
58-
$ cat openapi.yaml | openapi-spec-validator -
65+
cat openapi.yaml | openapi-spec-validator -
5966
6067
docker way:
6168

62-
.. code:: bash
69+
.. code-block:: bash
6370
64-
$ docker run -v path/to/openapi.yaml:/openapi.yaml --rm p1c2u/openapi-spec-validator /openapi.yaml
71+
docker run -v path/to/openapi.yaml:/openapi.yaml --rm p1c2u/openapi-spec-validator /openapi.yaml
6572
6673
or more pythonic way:
6774

68-
.. code:: bash
75+
.. code-block:: bash
6976
70-
$ python -m openapi_spec_validator openapi.yaml
77+
python -m openapi_spec_validator openapi.yaml
7178
72-
Examples
73-
********
79+
For more details, read about `CLI (Command Line Interface) <https://openapi-spec-validator.readthedocs.io/en/latest/cli.html>`__.
7480

75-
By default, OpenAPI spec version is detected. To validate spec:
81+
Python package
82+
**************
7683

7784
.. code:: python
7885
@@ -89,53 +96,18 @@ By default, OpenAPI spec version is detected. To validate spec:
8996
Traceback (most recent call last):
9097
...
9198
OpenAPIValidationError: 'info' is a required property
92-
93-
Add ``spec_url`` to validate spec with relative files:
94-
95-
.. code:: python
96-
97-
validate_spec(spec_dict, spec_url='file:///path/to/spec/openapi.yaml')
98-
99-
You can also validate spec from url:
100-
101-
.. code:: python
102-
103-
from openapi_spec_validator import validate_spec_url
104-
105-
# If no exception is raised by validate_spec_url(), the spec is valid.
106-
validate_spec_url('http://example.com/openapi.json')
107-
108-
In order to explicitly validate a:
109-
110-
* Swagger / OpenAPI 2.0 spec, import ``openapi_v2_spec_validator``
111-
* OpenAPI 3.0 spec, import ``openapi_v30_spec_validator``
112-
* OpenAPI 3.1 spec, import ``openapi_v31_spec_validator``
113-
114-
and pass the validator to ``validate_spec`` or ``validate_spec_url`` function:
115-
116-
.. code:: python
117-
118-
validate_spec(spec_dict, validator=openapi_v31_spec_validator)
119-
120-
You can also explicitly import ``openapi_v3_spec_validator`` which is a shortcut to the latest v3 release.
121-
122-
If you want to iterate through validation errors:
123-
124-
.. code:: python
125-
126-
from openapi_spec_validator import openapi_v3_spec_validator
12799
128-
errors_iterator = openapi_v3_spec_validator.iter_errors(spec)
100+
For more details, read about `Python package <https://openapi-spec-validator.readthedocs.io/en/latest/python.html>`__.
129101

130102
Related projects
131103
################
132104

133105
* `openapi-core <https://github.com/p1c2u/openapi-core>`__
134-
Python library that adds client-side and server-side support for the OpenAPI.
106+
Python library that adds client-side and server-side support for the OpenAPI v3.0 and OpenAPI v3.1 specification.
135107
* `openapi-schema-validator <https://github.com/p1c2u/openapi-schema-validator>`__
136-
Python library that validates schema against the OpenAPI Schema Specification v3.0.
108+
Python library that validates schema against the OpenAPI Schema Specification v3.0 and OpenAPI Schema Specification v3.1.
137109

138110
License
139111
#######
140112

141-
Copyright (c) 2017-2022, Artur Maciag, All rights reserved. Apache v2
113+
Copyright (c) 2017-2023, Artur Maciag, All rights reserved. Apache v2

‎docs/cli.rst

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
CLI (Command Line Interface)
2+
============================
3+
4+
.. md-tab-set::
5+
6+
.. md-tab-item:: Executable
7+
8+
Straight forward way:
9+
10+
.. code-block:: bash
11+
12+
openapi-spec-validator openapi.yaml
13+
14+
pipes way:
15+
16+
.. code-block:: bash
17+
18+
cat openapi.yaml | openapi-spec-validator -
19+
20+
.. md-tab-item:: Docker
21+
22+
.. code-block:: bash
23+
24+
docker run -v path/to/openapi.yaml:/openapi.yaml --rm p1c2u/openapi-spec-validator /openapi.yaml
25+
26+
.. md-tab-item:: Python interpreter
27+
28+
.. code-block:: bash
29+
30+
python -m openapi_spec_validator openapi.yaml
31+
32+
.. code-block:: bash
33+
34+
usage: openapi-spec-validator [-h] [--errors {best-match,all}]
35+
[--schema {2.0,3.0.0,3.1.0,detect}]
36+
filename
37+
38+
positional arguments:
39+
filename Absolute or relative path to file
40+
41+
options:
42+
-h, --help show this help message and exit
43+
--errors {best-match,all}
44+
Control error reporting. Defaults to "best-
45+
match", use "all" to get all subschema
46+
errors.
47+
--schema {2.0,3.0.0,3.1.0,detect}
48+
OpenAPI schema (default: detect)
49+

‎docs/conf.py

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
import openapi_spec_validator
2+
3+
project = "openapi-spec-validator"
4+
copyright = "2023, Artur Maciag"
5+
author = "Artur Maciag"
6+
7+
release = openapi_spec_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-spec-validator"
27+
28+
html_theme_options = {
29+
"analytics": {
30+
"provider": "google",
31+
"property": "G-SWHTV603PN",
32+
},
33+
"repo_url": "https://github.com/p1c2u/openapi-spec-validator/",
34+
"repo_name": "openapi-spec-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)