@team-supercharge/oasg 14.1.0-fix-android-publishing-group-998336b0.0 → 14.1.0

package/README.md

@@ -454,6 +454,20 @@ Common target parameters
 | packageName | Name of the generated NPM package | Y | - |
 | repository | URL of the NPM package registry | Y | - |
 
+##### Known issue: breaking dependencies
+
+The Angular target has a known issue related to dependency versioning. The generated Angular project's `package.json` currently defines multiple dependencies with flexible versions (e.g., using `^` or `~` in version constraints). This flexibility allows newer versions of dependencies (not to mention the transitive dependencies), to be pulled in, which can occasionally lead to breaking changes.
+
+A notable instance of this issue occurred with **Angular version 12**, which introduced changes that broke the build of generated projects. To address this specific case, we implemented a **temporary fix** in the `targets/angular/generate.sh` script. This script now manually installs problematic dependencies with fixed, validated versions.
+
+###### Long-Term Solution
+
+We are actively discussing a long-term solution to this issue. Potential approaches include implementing dependency version locking mechanisms (`package-lock.json`) per Angular versions.
+
+The temporary fix may not cover all future breaking changes from other dependencies. Projects using different versions of Angular may encounter issues if the fix does not align with their specific requirements.
+
+We welcome feedback and contributions to help address this issue.
+
 #### `react`
 
 ```json
@@ -683,6 +697,47 @@ TBD
 
 Publishing the PyPI packages is done with Twine. For authentication againts the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.
 
+
+#### `python-fastapi`
+
+```json
+{
+  "id": "server-python",
+  "type": "python-fastapi",
+  "source": "source-merged",
+  "packageName": "oasg_example",
+  "repositoryUrl": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/pypi"
+}
+```
+
+|Parameter| Description| Required | Default |
+|-|-|-|-|
+| packageName | Package nem for the project (convention: snake_case) | Y | - |
+| repositoryUrl | URL of the PyPI repository | Y | - |
+
+Building the distribution package requires Flit.
+Publishing the PyPI packages is done with Twine. For authentication againts the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.
+
+#### `python-fastapi-raw-request`
+
+```json
+{
+  "id": "server-python",
+  "type": "python-fastapi-raw-request",
+  "source": "source-merged",
+  "packageName": "oasg_example",
+  "repositoryUrl": "https://gitlab.supercharge.io/api/v4/projects/1226/packages/pypi"
+}
+```
+
+|Parameter| Description| Required | Default |
+|-|-|-|-|
+| packageName | Package nem for the project (convention: snake_case) | Y | - |
+| repositoryUrl | URL of the PyPI repository | Y | - |
+
+Building the distribution package requires Flit.
+Publishing the PyPI packages is done with Twine. For authentication againts the PiPI repository you need to set the `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables.
+
 #### `contract-testing`
 
 ```json
@@ -784,6 +839,41 @@ describe('Auth', function () {
 - array of enums in query/header/path/form parameters are not validated (stay as string)
 - no multidimensional array validation in DTOs
 
+**Validation availability:**
+<br> _List is not comprehensive, missing items are definitely not currently supported_
+
+| Validation                               | DTO | Query | Header | Path |
+| ---------------------------------------- | --- | ----- | ------ | ---- |
+| **Common**                               |     |       |        |      |
+| IsOptional _(!required)_                 | ✅  | ✅    | ✅     | ✅   |
+| IsDefined _(required)_                   | ✅  | ✅    | ✅     | ✅   |
+| **Types**                                |     |       |        |      |
+| IsBoolean                                | ✅  | ✅    | ✅     | ✅   |
+| IsDate _(isDate, isDateTime)_            | ❌  | ❌    | ❌     | ❌   |
+| IsString                                 | ✅  | ✅    | ✅     | ✅   |
+| IsNumber _(isNumber, isFloat, isDouble)_ | ✅  | ✅    | ✅     | ✅   |
+| IsInt _(isInt, isLong)_                  | ✅  | ✅    | ✅     | ✅   |
+| IsInt _(isShort, isUnboundedInteger)_    | ❌  | ❌    | ❌     | ❌   |
+| IsEnum                                   | ✅  | ✅    | ✅     | ✅   |
+| IsArray                                  | ✅  | ✅    | ✅     | ✅   |
+| **String**                               |     |       |        |      |
+| MinLength                                | ❌  | ❌    | ❌     | ❌   |
+| MaxLength                                | ❌  | ❌    | ❌     | ❌   |
+| Matches _(pattern)_                      | ✅  | ✅    | ✅     | ✅   |
+| IsUUID _(isUuid)_                        | ❌  | ❌    | ❌     | ❌   |
+| IsDataURI _(isUri)_                      | ❌  | ❌    | ❌     | ❌   |
+| IsEmail _(isEmail)_                      | ❌  | ❌    | ❌     | ❌   |
+| **Number**                               |     |       |        |      |
+| Min                                      | ❌  | ❌    | ❌     | ❌   |
+| Max                                      | ❌  | ❌    | ❌     | ❌   |
+| IsDivisibleBy _(multipleOf)_             | ❌  | ❌    | ❌     | ❌   |
+| IsDecimal _(isDecimal)_                  | ❌  | ❌    | ❌     | ❌   |
+| **Array**                                |     |       |        |      |
+| multidimensional array                   | ❌  | ❌    | ❌     | ❌   |
+| enum arrays                              | ✅  | ❌    | ❌     | ❌   |
+
+
+
 #### `openapi`
 
 ```json

package/bin/oasg

@@ -34,24 +34,26 @@ const PROXY_PORT = '9999';
 
 const DEFAULT_GENERATOR_MAPPING = {
   // client targets
-  "android":          { version: '7.0.1',   generator: 'kotlin' },
-  "angular":          { version: '7.0.1',   generator: 'typescript-angular' },
-  "feign":            { version: '7.0.1',   generator: 'spring' },
-  "feign-kotlin":     { version: '7.0.1',   generator: 'kotlin-spring' },
-  "flutter":          { version: '7.0.1',   generator: 'dart-dio' },
-  "ios":              { version: '7.0.1',   generator: 'swift5' },
-  "kmp":              { version: '7.8.0',   generator: 'kotlin' },
-  "python":           { version: '7.0.1',   generator: 'python' },
-  "react":            { version: '7.0.1',   generator: 'typescript-fetch' },
+  "android":                      { version: '7.0.1',   generator: 'kotlin' },
+  "angular":                      { version: '7.0.1',   generator: 'typescript-angular' },
+  "feign":                        { version: '7.0.1',   generator: 'spring' },
+  "feign-kotlin":                 { version: '7.0.1',   generator: 'kotlin-spring' },
+  "flutter":                      { version: '7.0.1',   generator: 'dart-dio' },
+  "ios":                          { version: '7.0.1',   generator: 'swift5' },
+  "kmp":                          { version: '7.8.0',   generator: 'kotlin' },
+  "python":                       { version: '7.0.1',   generator: 'python' },
+  "react":                        { version: '7.0.1',   generator: 'typescript-fetch' },
   // server targets
-  "nestjs":           { version: '7.0.1',   generator: 'typescript-angular' },
-  "spring":           { version: '7.0.1',   generator: 'spring' },
-  "spring-kotlin":    { version: '7.0.1',   generator: 'kotlin-spring' },
-  "dotnet":           { version: '7.8.0',   generator: 'csharp-functions' },
+  "nestjs":                       { version: '7.0.1',   generator: 'typescript-angular' },
+  "spring":                       { version: '7.0.1',   generator: 'spring' },
+  "spring-kotlin":                { version: '7.0.1',   generator: 'kotlin-spring' },
+  "python-fastapi":               { version: '7.8.0',   generator: 'python-fastapi' },
+  "python-fastapi-raw-request":   { version: '7.0.1',   generator: 'python-fastapi' },
+  "dotnet":                       { version: '7.8.0',   generator: 'csharp-functions' },
   // misc targets
-  "contract-testing": { version: '4.3.1',   generator: 'typescript-node' },
-  "openapi":          { version: undefined, generator: undefined },
-  "stubby":           { version: '4.3.1',   generator: 'stubby' },
+  "contract-testing":             { version: '4.3.1',   generator: 'typescript-node' },
+  "openapi":                      { version: undefined, generator: undefined },
+  "stubby":                       { version: '4.3.1',   generator: 'stubby' },
 };
 const DEFAULT_KTLINT_VERSION = '1.0.0';
 const BIN_FOLDER = 'out/.bin';

package/config.schema.yml

@@ -20,6 +20,8 @@ properties:
         - $ref: '#/targets/Android'
         - $ref: '#/targets/ios'
         - $ref: '#/targets/Python'
+        - $ref: '#/targets/PythonFastApi'
+        - $ref: '#/targets/PythonFastApiRawRequest'
         - $ref: '#/targets/ContractTesting'
         - $ref: '#/targets/NestJS'
         - $ref: '#/targets/OpenAPI'
@@ -297,6 +299,34 @@ targets:
         - packageName
         - repositoryUrl
 
+  PythonFastApi:
+    allOf:
+      - $ref: '#/targets/Base'
+      - properties:
+          type:
+            pattern: "^python-fastapi$"
+          packageName:
+            type: string
+          repositoryUrl:
+            type: string
+        required:
+        - packageName
+        - repositoryUrl
+
+  PythonFastApiRawRequest:
+    allOf:
+      - $ref: '#/targets/Base'
+      - properties:
+          type:
+            pattern: "^python-fastapi-raw-request$"
+          packageName:
+            type: string
+          repositoryUrl:
+            type: string
+        required:
+        - packageName
+        - repositoryUrl
+
   ContractTesting:
     allOf:
       - $ref: '#/targets/Base'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-supercharge/oasg",
-  "version": "14.1.0-fix-android-publishing-group-998336b0.0",
+  "version": "14.1.0",
   "description": "Node-based tool to lint OpenAPI documents and generate clients, servers and documentation from them",
   "author": "Supercharge",
   "license": "MIT",

package/targets/angular/generate.sh

@@ -15,5 +15,9 @@ java -jar $binary generate \
 
 cd out/$targetId
 npm install
+# This is a workaround for an issue with the angular generator. Root cause is the missing package-lock.json: https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator/src/main/resources/typescript-angular
+# some of the transitive dependency has @types/node@": "*" in their package.json
+# use "npm explain @types/node" in the generated folder (./out/$TARGET) to get more info
+npm install --save-dev @types/node@20.15.0
 npm run build
 cd ../..

package/targets/python/generate.sh

@@ -2,9 +2,12 @@
 
 source $(dirname "$0")/../common.sh
 
-# change npm pre-release syntax (with - after semver) to python local syntax (with + after semver)
-version=$(echo $version | sed 's/-/\+/')
-echo "[NOTE] version updated to: ${version}"
+# if the version contains a `-` character, then use PEP 440 beta version syntax
+# example: 1.0.0-beta.1 -> 1.0.0b0+beta.1
+if [[ $version == *"-"* ]]; then
+  version=$(echo $version | sed 's/-/b0+/')
+  echo "[NOTE] version updated to: ${version}"
+fi
 
 rm -rf out/$targetId
 mkdir -p out/$targetId

package/targets/python-fastapi/generate.sh

@@ -0,0 +1,32 @@
+#/bin/bash
+
+source $(dirname "$0")/../common.sh
+
+# if the version contains a `-` character, then use PEP 440 beta version syntax
+# example: 1.0.0-beta.1 -> 1.0.0b0+beta.1
+if [[ $version == *"-"* ]]; then
+  version=$(echo $version | sed 's/-/b0+/')
+  echo "[NOTE] version updated to: ${version}"
+fi
+
+rm -rf out/$targetId
+mkdir -p out/$targetId
+
+java -jar $binary generate \
+  -g $generatorId \
+  -i $openApiFile \
+  -t $templateDir \
+  -o out/$targetId \
+  -c $(dirname "$0")/generator-config.json \
+  -p "packageVersion=$version,packageName=$packageName" $generatorCustomArgs
+
+cd out/$targetId
+
+touch "src/$packageName/__init__.py"
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
+pip install flit==3.9.0
+flit build --no-use-vcs
+
+cd ../../

package/targets/python-fastapi/generator-config.json

@@ -0,0 +1,7 @@
+{
+  "inlineSchemaOptions": {
+    "ARRAY_ITEM_SUFFIX": "",
+    "MAP_ITEM_SUFFIX": "",
+    "SKIP_SCHEMA_REUSE": "true"
+  }
+}

package/targets/python-fastapi/publish.sh

@@ -0,0 +1,9 @@
+#/bin/bash
+
+source $(dirname "$0")/../common.sh
+
+cd out/$targetId
+source venv/bin/activate
+pip install importlib_metadata==7.2.1 twine==4.0.2
+python3 -m twine upload --repository-url $repositoryUrl dist/*
+cd ../..

package/targets/python-fastapi-raw-request/generate.sh

@@ -0,0 +1,32 @@
+#/bin/bash
+
+source $(dirname "$0")/../common.sh
+
+# if the version contains a `-` character, then use PEP 440 beta version syntax
+# example: 1.0.0-beta.1 -> 1.0.0b0+beta.1
+if [[ $version == *"-"* ]]; then
+  version=$(echo $version | sed 's/-/b0+/')
+  echo "[NOTE] version updated to: ${version}"
+fi
+
+rm -rf out/$targetId
+mkdir -p out/$targetId
+
+java -jar $binary generate \
+  -g $generatorId \
+  -i $openApiFile \
+  -t $templateDir \
+  -o out/$targetId \
+  -c $(dirname "$0")/generator-config.json \
+  -p "packageVersion=$version,packageName=$packageName" $generatorCustomArgs
+
+cd out/$targetId
+
+touch "src/$packageName/__init__.py"
+python3 -m venv venv
+source venv/bin/activate
+pip install --upgrade pip
+pip install flit==3.9.0
+flit build --no-use-vcs
+
+cd ../../

package/targets/python-fastapi-raw-request/generator-config.json

@@ -0,0 +1,7 @@
+{
+  "inlineSchemaOptions": {
+    "ARRAY_ITEM_SUFFIX": "",
+    "MAP_ITEM_SUFFIX": "",
+    "SKIP_SCHEMA_REUSE": "true"
+  }
+}

package/targets/python-fastapi-raw-request/publish.sh

@@ -0,0 +1,9 @@
+#/bin/bash
+
+source $(dirname "$0")/../common.sh
+
+cd out/$targetId
+source venv/bin/activate
+pip install importlib_metadata==7.2.1 twine==4.0.2
+python3 -m twine upload --repository-url $repositoryUrl dist/*
+cd ../..

package/targets/python-fastapi-raw-request/templates/README.mustache

@@ -0,0 +1,43 @@
+# OpenAPI generated FastAPI server
+
+This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
+
+- API version: {{appVersion}}
+{{^hideGenerationTimestamp}}
+- Build date: {{generatedDate}}
+{{/hideGenerationTimestamp}}
+- Build package: {{generatorClass}}
+
+## Requirements.
+
+Python >= {{{generatorLanguageVersion}}}
+
+## Installation & Usage
+
+To run the server, please execute the following from the root directory:
+
+```bash
+pip3 install -r requirements.txt
+pip3 install uvicorn
+uvicorn --app-dir src {{packageName}}.main:app --host 0.0.0.0 --port {{serverPort}}
+```
+
+and open your browser at `http://localhost:{{serverPort}}/docs/` to see the docs.
+
+## Running with Docker
+
+To run the server on a Docker container, please execute the following from the root directory:
+
+```bash
+docker-compose up --build
+```
+
+## Tests
+
+To run the tests:
+
+```bash
+pip3 install pytest
+pip3 install httpx
+PYTHONPATH=src pytest tests
+```

package/targets/python-fastapi-raw-request/templates/api.mustache

@@ -0,0 +1,62 @@
+# coding: utf-8
+
+from typing import Dict, List  # noqa: F401
+import importlib
+import pkgutil
+
+from {{apiPackage}}.{{classFilename}}_{{baseSuffix}} import Base{{classname}}
+
+from fastapi import (  # noqa: F401
+    APIRouter,
+    Body,
+    Cookie,
+    Depends,
+    Form,
+    Header,
+    Path,
+    Query,
+    Request,
+    Response,
+    Security,
+    status,
+)
+
+from {{modelPackage}}.extra_models import TokenModel  # noqa: F401
+{{#imports}}
+{{import}}
+{{/imports}}
+
+router = APIRouter()
+
+{{#operations}}
+{{#operation}}
+@router.{{#lambda.lowercase}}{{httpMethod}}{{/lambda.lowercase}}(
+    "{{path}}",
+    responses={
+        {{#responses}}
+        {{code}}: {{=<% %>=}}{<%#dataType%>"model": <%dataType%>, "description": "<%message%>"<%/dataType%><%^dataType%>"description": "<%message%>"<%/dataType%>}<%={{ }}=%>,
+        {{/responses}}
+    },
+    tags=[{{#tags}}"{{name}}"{{^-last}},{{/-last}}{{/tags}}],
+    {{#summary}}
+    summary="{{.}}",
+    {{/summary}}
+    {{#description}}
+    description = "{{.}}",
+    {{/description}}
+    response_model_by_alias=True,
+)
+async def {{operationId}}(
+    request: Request,
+    {{#allParams}}
+    {{>endpoint_argument_definition}},
+    {{/allParams}}
+) -> Response: # -> {{returnType}}{{^returnType}}None{{/returnType}}
+    {{#notes}}"""{{.}}"""
+    return await Base{{classname}}.subclasses[0]().{{operationId}}(request{{#allParams}}, {{>impl_argument}}{{/allParams}}){{/notes}}{{^notes}}...{{/notes}}
+{{^-last}}
+
+
+{{/-last}}
+{{/operation}}
+{{/operations}}

package/targets/python-fastapi-raw-request/templates/base_api.mustache

@@ -0,0 +1,32 @@
+# coding: utf-8
+
+from typing import ClassVar, Dict, List, Tuple  # noqa: F401
+from fastapi import Request, Response
+
+{{#imports}}
+{{import}}
+{{/imports}}
+
+class Base{{classname}}:
+    subclasses: ClassVar[Tuple] = ()
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        Base{{classname}}.subclasses = Base{{classname}}.subclasses + (cls,)
+
+{{#operations}}
+{{#operation}}
+    async def {{operationId}}(
+        self,
+        request: Request,
+        {{#allParams}}
+        {{>impl_argument_definition}},
+        {{/allParams}}
+    ) -> Response: # -> {{returnType}}{{^returnType}}None{{/returnType}}
+        {{#notes}}"""{{.}}"""
+        ...{{/notes}}{{^notes}}...{{/notes}}
+{{^-last}}
+
+{{/-last}}
+{{/operation}}
+{{/operations}}

package/targets/python-fastapi-raw-request/templates/endpoint_argument_definition.mustache

@@ -0,0 +1 @@
+{{#isPathParam}}{{baseName}}{{/isPathParam}}{{^isPathParam}}{{paramName}}{{/isPathParam}}: {{>param_type}} = {{#isPathParam}}Path{{/isPathParam}}{{#isHeaderParam}}Header{{/isHeaderParam}}{{#isFormParam}}Form{{/isFormParam}}{{#isQueryParam}}Query{{/isQueryParam}}{{#isCookieParam}}Cookie{{/isCookieParam}}{{#isBodyParam}}Body{{/isBodyParam}}({{&defaultValue}}{{^defaultValue}}{{#isPathParam}}...{{/isPathParam}}{{^isPathParam}}None{{/isPathParam}}{{/defaultValue}}, description="{{description}}"{{#isQueryParam}}, alias="{{baseName}}"{{/isQueryParam}}{{#isLong}}{{#minimum}}, ge={{.}}{{/minimum}}{{#maximum}}, le={{.}}{{/maximum}}{{/isLong}}{{#isInteger}}{{#minimum}}, ge={{.}}{{/minimum}}{{#maximum}}, le={{.}}{{/maximum}}{{/isInteger}}{{#pattern}}, regex=r"{{.}}"{{/pattern}}{{#minLength}}, min_length={{.}}{{/minLength}}{{#maxLength}}, max_length={{.}}{{/maxLength}})

package/targets/python-fastapi-raw-request/templates/pyproject_toml.mustache

@@ -0,0 +1,35 @@
+[project]
+name = "{{packageName}}"
+version = "{{packageVersion}}"
+description = "{{appDescription}}"
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 88
+exclude = '''
+(
+  /(
+      \.eggs         # exclude a few common directories in the
+    | \.git          # root of the project
+    | \.hg
+    | \.mypy_cache
+    | \.tox
+    | \.venv
+    | _build
+    | buck-out
+    | build
+    | dist
+  )/
+)
+'''
+
+[tool.isort]
+profile = "black"
+skip = [
+    '.eggs', '.git', '.hg', '.mypy_cache', '.nox', '.pants.d', '.tox',
+    '.venv', '_build', 'buck-out', 'build', 'dist', 'node_modules', 'venv',
+]
+skip_gitignore = true

package/targets/python-fastapi-raw-request/templates/requirements.mustache

@@ -0,0 +1,2 @@
+fastapi==0.109.2
+pydantic==2.6