Merge pull request #55 from dapper91/dev

- openapi error examples support added.
- openapi errors schema support added.
- multiple extractors support added.
- docstring extractor bug fixed.

CHANGELOG.rst

@@ -1,6 +1,15 @@
 Changelog
 =========
 
+1.4.0 (2021-11-30)
+------------------
+
+- openapi error examples support added.
+- openapi errors schema support added.
+- multiple extractors support added.
+- docstring extractor bug fixed.
+
+
 1.3.5 (2021-11-03)
 ------------------
 

README.rst

@@ -544,15 +544,15 @@ and Swagger UI web tool with basic auth:
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -589,10 +589,10 @@ and Swagger UI web tool with basic auth:
  user_id='c47726c6-a232-45f1-944f-60b98966ff1b',
  ),
  result={
-  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
-  'name': 'Alex',
-  'surname': 'Smith',
-  'age': 25,
+ 'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
+ 'name': 'John',
+ 'surname': 'Doe',
+ 'age': 25,
  },
  ),
  ],
@@ -608,11 +608,11 @@ and Swagger UI web tool with basic auth:
  :raise NotFoundError: user not found
  """
 
- user = flask.current_app.users_db.get(user_id)
+ user = flask.current_app.users_db.get(user_id.hex)
  if not user:
  raise NotFoundError()
 
- return UserOut(**user.dict())
+ return UserOut(id=user_id, **user.dict())
 
 
  @specs.annotate(
@@ -638,7 +638,7 @@ and Swagger UI web tool with basic auth:
  :raise NotFoundError: user not found
  """
 
- user = flask.current_app.users_db.pop(user_id, None)
+ user = flask.current_app.users_db.pop(user_id.hex, None)
  if not user:
  raise NotFoundError()
 
@@ -660,7 +660,7 @@ and Swagger UI web tool with basic auth:
  ),
  ),
  security=[
- dict(basicAuth=[])
+ dict(basicAuth=[]),
  ],
  schema_extractor=extractors.pydantic.PydanticSchemaExtractor(),
  ui=specs.SwaggerUI(),

docs/source/pjrpc/quickstart.rst

@@ -474,15 +474,15 @@ Swagger UI web tool with basic auth:
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -520,8 +520,8 @@ Swagger UI web tool with basic auth:
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),

docs/source/pjrpc/specification.rst

@@ -65,6 +65,8 @@ and :py:class:`pjrpc.server.specs.extractors.docstring.DocstringSchemaExtractor`
 They uses `pydantic <https://pydantic-docs.helpmanual.io/>`_ models or python docstrings for method summary,
 description, errors, examples and schema extraction respectively. You can implement your own schema extractor
 inheriting it from :py:class:`pjrpc.server.specs.extractors.BaseSchemaExtractor` and implementing abstract methods.
+Multiple schema extractors could be used simultaneously using parameter ``schema_extractors``. Final schema
+will be merged using that extractors in reverse order (former extractor rewrites the result of the later ones).
 
 .. code-block:: python
 
@@ -76,15 +78,15 @@ inheriting it from :py:class:`pjrpc.server.specs.extractors.BaseSchemaExtractor`
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),

docs/source/pjrpc/webui.rst

@@ -144,15 +144,15 @@ using flask web framework:
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -190,8 +190,8 @@ using flask web framework:
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),

examples/django/mysite/jsonrpc/users.py

@@ -57,15 +57,15 @@ class NotFoundError(pjrpc.exc.JsonRpcError):
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -100,8 +100,8 @@ def add_user(request: HttpRequest, user: UserIn) -> UserOut:
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),

examples/openapi_aiohttp.py

@@ -4,6 +4,7 @@
 import pydantic
 from aiohttp import helpers, web
 
+import pjrpc.server.specs.extractors.docstring
 import pjrpc.server.specs.extractors.pydantic
 from pjrpc.server.integration import aiohttp as integration
 from pjrpc.server.validators import pydantic as validators
@@ -83,15 +84,15 @@ class NotFoundError(pjrpc.exc.JsonRpcError):
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -130,8 +131,8 @@ def add_user(request: web.Request, user: UserIn) -> UserOut:
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -207,7 +208,10 @@ def delete_user(request: web.Request, user_id: uuid.UUID) -> None:
  security=[
  dict(basicAuth=[]),
  ],
- schema_extractor=extractors.pydantic.PydanticSchemaExtractor(),
+ schema_extractors=[
+ extractors.docstring.DocstringSchemaExtractor(),
+ extractors.pydantic.PydanticSchemaExtractor(),
+ ],
  ui=specs.SwaggerUI(),
  # ui=specs.RapiDoc(),
  # ui=specs.ReDoc(),

examples/openapi_aiohttp_subendpoints.py

@@ -4,6 +4,7 @@
 import pydantic
 from aiohttp import web
 
+import pjrpc.server.specs.extractors.docstring
 import pjrpc.server.specs.extractors.pydantic
 from pjrpc.server.integration import aiohttp as integration
 from pjrpc.server.validators import pydantic as validators
@@ -61,15 +62,15 @@ class AlreadyExistsError(pjrpc.exc.JsonRpcError):
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -166,7 +167,10 @@ def add_post(request: web.Request, post: PostIn) -> PostOut:
  security=[
  dict(basicAuth=[]),
  ],
- schema_extractor=extractors.pydantic.PydanticSchemaExtractor(),
+ schema_extractors=[
+ extractors.docstring.DocstringSchemaExtractor(),
+ extractors.pydantic.PydanticSchemaExtractor(),
+ ],
  ui=specs.SwaggerUI(),
  # ui=specs.RapiDoc(),
  # ui=specs.ReDoc(),

examples/openapi_flask.py

@@ -7,6 +7,7 @@
 import flask_cors
 from werkzeug import security
 
+import pjrpc.server.specs.extractors.docstring
 import pjrpc.server.specs.extractors.pydantic
 from pjrpc.server.integration import flask as integration
 from pjrpc.server.validators import pydantic as validators
@@ -89,15 +90,15 @@ class NotFoundError(pjrpc.exc.JsonRpcError):
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -134,10 +135,10 @@ def add_user(user: UserIn) -> UserOut:
  user_id='c47726c6-a232-45f1-944f-60b98966ff1b',
  ),
  result={
-  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
-  'name': 'Alex',
-  'surname': 'Smith',
-  'age': 25,
+ 'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
+ 'name': 'John',
+ 'surname': 'Doe',
+ 'age': 25,
  },
  ),
  ],
@@ -207,7 +208,10 @@ def delete_user(user_id: uuid.UUID) -> None:
  security=[
  dict(basicAuth=[]),
  ],
- schema_extractor=extractors.pydantic.PydanticSchemaExtractor(),
+ schema_extractors=[
+ extractors.docstring.DocstringSchemaExtractor(),
+ extractors.pydantic.PydanticSchemaExtractor(),
+ ],
  ui=specs.SwaggerUI(),
  # ui=specs.RapiDoc(),
  # ui=specs.ReDoc(),

examples/openapi_flask_subendpoints.py

@@ -4,6 +4,7 @@
 import flask
 import pydantic
 
+import pjrpc.server.specs.extractors.docstring
 import pjrpc.server.specs.extractors.pydantic
 from pjrpc.server.integration import flask as integration
 from pjrpc.server.validators import pydantic as validators
@@ -62,15 +63,15 @@ class AlreadyExistsError(pjrpc.exc.JsonRpcError):
  summary="Simple example",
  params=dict(
  user={
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
  result={
  'id': 'c47726c6-a232-45f1-944f-60b98966ff1b',
- 'name': 'Alex',
- 'surname': 'Smith',
+ 'name': 'John',
+ 'surname': 'Doe',
  'age': 25,
  },
  ),
@@ -165,7 +166,10 @@ def add_post(post: PostIn) -> PostOut:
  security=[
  dict(basicAuth=[]),
  ],
- schema_extractor=extractors.pydantic.PydanticSchemaExtractor(),
+ schema_extractors=[
+ extractors.docstring.DocstringSchemaExtractor(),
+ extractors.pydantic.PydanticSchemaExtractor(),
+ ],
  ui=specs.SwaggerUI(),
  ),
 )