add support for splitting OpenAPI specification into multiple files. (#30)

* add support for splitting OpenAPI specification into multiple files.

Author: flask-pro

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 - repo: https://github.com/asottile/pyupgrade
-  rev: v3.15.0
+  rev: v3.15.1
   hooks:
   - id: pyupgrade
     args: [--py39-plus]
@@ -15,7 +15,7 @@ repos:
   - id: check-builtin-literals
   - id: check-toml
 - repo: https://github.com/psf/black
-  rev: 23.10.0
+  rev: 24.2.0
   hooks:
   - id: black
 - repo: https://github.com/asottile/reorder_python_imports
@@ -30,7 +30,7 @@ repos:
   - id: text-unicode-replacement-char
     exclude: .js$
 - repo: https://github.com/pycqa/flake8
-  rev: 6.1.0
+  rev: 7.0.0
   hooks:
   - id: flake8
     additional_dependencies:
@@ -42,9 +42,19 @@ repos:
   hooks:
   - id: checkmake
 - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
-  rev: v2.11.0
+  rev: v2.12.0
   hooks:
   - id: pretty-format-yaml
     args: [--autofix, --indent, '2']
   - id: pretty-format-toml
     args: [--autofix, --indent, '2']
+- repo: https://codeberg.org/frnmst/md-toc
+  rev: 8.2.3
+  hooks:
+  - id: md-toc
+    args: [-p, github]
+- repo: https://github.com/asottile/pyupgrade
+  rev: v3.15.1
+  hooks:
+  - id: pyupgrade
+    args: [--py39-plus]

.python-version

@@ -1 +1 @@
-3.11
+3.12

CHANGES.md

@@ -1,3 +1,7 @@
+## Version 0.16.0
+
+* Add support for splitting OpenAPI specification into multiple files.
+
 ## Version 0.15.0
 
 * Add specification experimental validator for OpenAPI 3.1.

Makefile

@@ -3,7 +3,7 @@
 
 venv:
 	# Create virtual environment.
-	python3.11 -m venv venv
+	python3.12 -m venv venv
 	./venv/bin/pip3 -q install --upgrade pip setuptools wheel
 	./venv/bin/pip3 -q install -e ".[dev]"
 	./venv/bin/pip3 -q install -e .

README.md

@@ -1,43 +1,76 @@
 # Flask-First
 
-Flask extension for using "specification first" principle.
+Flask extension for using "specification first" and "API-first" principles.
 
-Features:
+<!--TOC-->
+
+- [Flask-First](#flask-first)
+  - [Features](#features)
+    - [Limitations](#limitations)
+  - [Installation](#installation)
+  - [Settings](#settings)
+  - [Data types](#data-types)
+  - [Examples](#examples)
+    - [Simple example](#simple-example)
+    - [Specification from multiple file](#specification-from-multiple-file)
+    - [CORS support](#cors-support)
+  - [Additional documentation](#additional-documentation)
+
+<!--TOC-->
+
+## Features
 
 * `Application Factory` supported.
-* Validating and serializing arguments from `request.headers` to `request.first_headers`.
-* Validating and serializing arguments from `request.view_args` to `request.first_view_args`.
-* Validating and serializing arguments from `request.args` to `request.first_args`.
-* Validating and serializing arguments from `request.cookies` to `request.first_cookies`.
-* Validating and serializing arguments from `request.json` to `request.first_json`.
-* Validating headers from request.
-* Validating cookies from request.
-* Validating path parameters from request.
-* Validating parameters from request.
-* Validating JSON from request.
-* Validating JSON from response.
+* Validating and serializing headers of request from `request.headers` to `request.first_headers`.
+* Validating and serializing path parameters of request from `request.view_args`
+  to `request.first_view_args`.
+* Validating and serializing arguments of request from `request.args` to `request.first_args`.
+* Validating and serializing cookies of request from `request.cookies` to `request.first_cookies`.
+* Validating and serializing JSON of request from `request.json` to `request.first_json`.
+* Validating JSON from response for debugging.
 * Provides a Swagger UI.
+* Support OpenAPI version 3.1.0.
+* Support specification from multiple file.
 
-Limitations
-----
+### Limitations
 
 Will be added in future releases.
 
-* Full specification in one file.
 * Authorization not supported.
 
-## Installing
+## Installation
 
 Recommended using the latest version of Python. Flask-First supports Python 3.9 and newer.
 
 Install and update using `pip`:
 
 ```shell
-$ pip install flask_first
+$ pip install -U flask_first
 ```
 
-Simple example
---------------
+## Settings
+
+`FIRST_RESPONSE_VALIDATION` - Default: `False`. Enabling response body validation. Useful when
+developing. Must be disabled in a production environment.
+
+## Data types
+
+Supported formats for string type field:
+
+* uuid
+* date-time
+* date
+* time
+* email
+* ipv4
+* ipv6
+* uri
+* binary
+
+## Examples
+
+### Simple example
+
 OpenAPI 3 specification file `openapi.yaml`:
 
 ```yaml
@@ -48,16 +81,16 @@ info:
 paths:
   /{name}:
     parameters:
-      - name: name
-        in: path
-        required: true
-        schema:
-          type: string
+    - name: name
+      in: path
+      required: true
+      schema:
+        type: string
     get:
       operationId: index
       summary: Returns a list of items
       responses:
-        '200':
+        200:
           description: OK
           content:
             application/json:
@@ -85,14 +118,13 @@ first = First(path_to_spec, app=app, swagger_ui_path='/docs')
 
 
 def index(name):
-  return {'message': name}
+    return {'message': name}
 
 
 first.add_view_func(index)
 
 if __name__ == '__main__':
-  app.run()
-
+    app.run()
 ```
 
 Run application:
@@ -104,12 +136,58 @@ $ python main.py
 Check url in browser `http://127.0.0.1:5000/username`. Check SwaggerUI url in
 browser `http://127.0.0.1:5000/docs`.
 
-## Settings
+### Specification from multiple file
 
-`FIRST_RESPONSE_VALIDATION` - Default: `False`. Enabling response body validation. Useful when
-developing. May be disabled in a production environment.
+Flask-First supported specification OpenAPI from multiple files. You need create root file for
+specification with name `openapi.yaml`.
 
-## CORS support
+Root file `openapi.yaml`:
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Simple API for Flask-First
+  version: 1.0.0
+paths:
+  /{name}:
+    $ref: 'name.openapi.yaml#/name'
+components:
+  schemas:
+    MessageField:
+      type: string
+      description: Field for message.
+```
+
+Child file `name.openapi.yaml`:
+
+```yaml
+name:
+  parameters:
+    - name: name
+      in: path
+      required: true
+      schema:
+      type: string
+  get:
+    operationId: index
+    summary: Returns a list of items
+    responses:
+      '200':
+        $ref: '#/components/responses/ResponseOK'
+components:
+  responses:
+    ResponseOK:
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                $ref: 'openapi.yaml#/components/schemas/MessageField'
+```
+
+### CORS support
 
 Your need enable CORS in Flask and adding `OPTIONS` method in your specification. Example:
 
@@ -125,34 +203,20 @@ paths:
     options:
       summary: CORS support
       responses:
-        200:
-          headers:
-            Access-Control-Allow-Origin:
-              schema:
-                type: string
-            Access-Control-Allow-Methods:
-              schema:
-                type: string
-            Access-Control-Allow-Headers:
-              schema:
-                type: string
-          content: { }
+      200:
+        headers:
+          Access-Control-Allow-Origin:
+            schema:
+              type: string
+          Access-Control-Allow-Methods:
+            schema:
+              type: string
+          Access-Control-Allow-Headers:
+            schema:
+              type: string
+        content: { }
 ```
 
-## Data types
-
-Supported formats for string type field:
-
-* uuid
-* date-time
-* date
-* time
-* email
-* ipv4
-* ipv6
-* uri
-* binary
-
 ## Additional documentation
 
 * [OpenAPI Documentation](https://swagger.io/specification/).

pyproject.toml

@@ -27,15 +27,15 @@ version = "0.15.0"
 
 [project.optional-dependencies]
 dev = [
-  "bandit==1.7.5",
-  "build==1.0.3",
-  "mypy==1.6.1",
-  "pre-commit==3.5.0",
-  "pytest==7.4.2",
+  "bandit==1.7.7",
+  "build==1.1.1",
+  "mypy==1.8.0",
+  "pre-commit==3.6.2",
+  "pytest==8.0.2",
   "pytest-cov==4.1.0",
-  "python-dotenv==1.0.0",
-  "tox==4.11.3",
-  "twine==4.0.2"
+  "python-dotenv==1.0.1",
+  "tox==4.13.0",
+  "twine==5.0.0"
 ]
 
 [project.urls]

src/flask_first/__init__.py

@@ -1,4 +1,3 @@
-"""Flask extension for using “specification first” principle."""
 import re
 from pathlib import Path
 from typing import Any
@@ -103,7 +102,8 @@ def _extract_data_from_request(
 
         return method, route, headers, view_args, args, cookies, json
 
-    def _resolved_params(self, payload: MultiDict) -> dict:
+    @staticmethod
+    def _resolved_params(payload: MultiDict) -> dict:
         # payload.to_dict(flat=False) serializing all arguments as list for correct receipt of
         # arguments of same name:
         # {'first_arg': ['1'], 'second_arg': ['10'], 'args_list': ['1', '2']}
@@ -117,7 +117,8 @@ def _resolved_params(self, payload: MultiDict) -> dict:
 
         return serialized_payload
 
-    def _arg_to_list(self, args: dict, schema_fields: dict) -> dict:
+    @staticmethod
+    def _arg_to_list(args: dict, schema_fields: dict) -> dict:
         for arg in args:
             arg_value = schema_fields.get(arg, ...)
 

src/flask_first/first/exceptions.py

@@ -5,6 +5,10 @@ class FirstException(Exception):
     """Common exception."""
 
 
+class FirstOpenAPIResolverError(FirstException):
+    """Exception for specification resolver error."""
+
+
 class FirstOpenAPIValidation(FirstException):
     """Exception for specification validation error."""