https://github.com/amartus/lsoblendingtool
A project to support a consistent code-base generation from MEF API definitions and product specifications
https://github.com/amartus/lsoblendingtool
oas swagger
Last synced: 7 months ago
JSON representation
A project to support a consistent code-base generation from MEF API definitions and product specifications
- Host: GitHub
- URL: https://github.com/amartus/lsoblendingtool
- Owner: Amartus
- License: apache-2.0
- Created: 2020-04-08T12:34:16.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-10T12:22:33.000Z (over 1 year ago)
- Last Synced: 2025-03-22T10:48:56.591Z (7 months ago)
- Topics: oas, swagger
- Language: Java
- Size: 20.9 MB
- Stars: 2
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SonataBlendingTool
A project to support a consistent code-base generation from MEF API definitions and product specifications
# Project build
Project build with Maven
```shell script
mvn clean package
```
# Project run (CLI)
Project requires Java runtime in version 17 or greater.
```shell script
java -jar blender-all-in.jar [args]
```
## Tool `generate` command synopsis
```shell script
NAME
sonata-blending-tool-cli generate - Generate code using configuration.
SYNOPSIS
sonata-blending-tool-cli generate
[ {-b | --blending-schema} ... ]
[ {-c | --config} ]
[ {-d | --spec-root-dir} ]
[ {-e | -encoding} ]
[ {-i | --input-spec} ]
[ {-m | --model-name} ]
[ --strict-mode ]
OPTIONS
-b , --blending-schema
sets of specifications (e.g. specific product or service
definitions) you would like to integrate
This option is part of the group 'allOrSelective' from which only
one option may be specified
-c , --config
Path to configuration file configuration file. It can be json or
yaml.If file is json, the content should have the format
{"optionKey":"optionValue", "optionKey1":"optionValue1"...}.If file
is yaml, the content should have the format optionKey:
optionValueSupported options can be different for each language.
Run config-help -g {generator name} command for language specific
config options.
This option may occur a maximum of 1 times
-d , --spec-root-dir
sets of product specification root directory for specifications you
would like to integrate
This option may occur a maximum of 1 times
-e , -encoding
encoding used to read API and product definitions. By default
system encoding is used
-i , --input-spec
location of the OpenAPI spec, as URL or file (required)
This option may occur a maximum of 1 times
-m , --model-name
Model which will be hosting product specific extensions (e.g.
MEFProductConfiguration)
--strict-mode
Verify that model to be augmented allows for extension (contains
discriminator definition).
If strict-mode is `false` tool will add a discriminator on the fly
if possible.
```
### Usage example
Assuming you have a valid spring generator configuration
(as explained [here](https://openapi-generator.tech/docs/generators/spring)) in `configurations/spring`
```shell script
java -jar blender-all-in.jar generate -i .\productApi\serviceability\offeringQualification\productOfferingQualificationManagement.api.yaml \
-c ./configurations/spring/spring-server.yaml \
-d .\productSchema\carrierEthernet \
-b accessEline\accessElineOvc.yaml -b carrierEthernetOperatorUni\carrierEthernetOperatorUni.yaml
```
## Tool `blend` command synopsis
Blend command generates an OAS 3 definition of combined API and product specifications
```shell script
NAME
sonata-blending-tool-cli blend - Blend Product / Service Specifications
into OpenAPI.
SYNOPSIS
sonata-blending-tool-cli blend
[ {-b | --blending-schema} ... ]
[ {-d | --spec-root-dir} ]
[ {-discover | --auto-discover} ]
[ {-e | -encoding} ]
[ {-f | --force-override} ] [ {-i | --input-spec} ]
[ {-m | --model-name} ]
[ --no-resolve-external ]
[ {-o | --output} ]
[ --path-security ] [ --sorted ]
[ --strict-mode ] [ --validate ]
OPTIONS
-b , --blending-schema
sets of specifications (e.g. specific product or service
definitions) you would like to integrate
This option is part of the group 'allOrSelective' from which only
one option may be specified
-d , --spec-root-dir
root directory for specifications.
This option may occur a maximum of 1 times
-discover, --auto-discover
Try to use a parent type name from x-mef-target extension in
schema. If not defined the fallback is to take 'model-name'
-e , -encoding
encoding used to read API and product definitions. By default
system encoding is used
-f, --force-override
Override output if exist
This option may occur a maximum of 1 times
-i , --input-spec
location of the OpenAPI spec, as URL or file (required)
This option may occur a maximum of 1 times
-m , --model-name
Model which will be hosting product specific extensions (e.g.
MEFProductConfiguration)
--no-resolve-external
Do not resolve external references. By default external references
are resolved.
This option may occur a maximum of 1 times
-o , --output
Output file name. Throws exception if file exists. If it is not
provided output file is 'output-spec'.modified
This option may occur a maximum of 1 times
--path-security
mechanism to use to secure API paths. default disabled
This options value is restricted to the following set of values:
oauth2
oauth2_simple
disabled
--sorted
sort data types in a lexical order
This option may occur a maximum of 1 times
--strict-mode
Verify that model to be augmented allows for extension (contains
discriminator definition).
If strict-mode is `false` tool will add a discriminator on the fly
if possible.
--validate
Validate consistency of OAS definition with its 3.0.x json schema
definition
This option may occur a maximum of 1 times
```
### Usage example for Sonata
Assumption is that this command is run from root of the Sonata SDK directory and jar file is in the same directory.
```shell script
java -jar blender-all-in.jar blend -i .\productApi\serviceability\offeringQualification\productOfferingQualificationManagement.api.yaml \
-d .\productSchema\carrierEthernet \
-b accessEline\accessElineOvc.yaml \
-b carrierEthernetOperatorUni\carrierEthernetOperatorUni.yaml
```
### Usage example for Legato
Assumption is that this command is run from root of the Legato SDK directory and jar file is in the same directory.
```shell script
java -jar blender-all-in.jar blend -d spec/legato/carrierEthernet -m MefServiceConfiguration \
-i ./api/legato/serviceProvisioning/serviceOrdering/v4/serviceOrderingApi.openapi.yaml \
-b carrierEthernetOvc.yaml \
-b carrierEthernetSubscriberUni.yaml
```
### Additional features
#### Auto-discover mode
If a schema to blend defines `x-mef-target` extension it can be used as a target class name for given type.
To enable this feature please use `-discover` flag. In auto-discover mode if `x-mef-target` is not defined for the schema
the `model-name` will be used as a fallback.
## Tool `merge` command synopsis
Merge command generates an OAS 3 definition that is a minimal OAS file including `components/schemas` only
with schema definition for all selected `blending-schema`s.
```shell script
SYNOPSIS
sonata-blending-tool-cli merge
[ {-b | --blending-schema} ... ]
[ {-d | --spec-root-dir} ]
[ {-discover | --auto-discover} ]
[ {-f | --force-override} ]
[ {-m | --model-name} ]
{-o | --output} [ --sorted ]
OPTIONS
-b , --blending-schema
sets of specifications (e.g. specific product or service
definitions) you would like to integrate
This option is part of the group 'allOrSelective' from which only
one option may be specified
-d , --spec-root-dir
This option may occur a maximum of 1 times
-discover, --auto-discover
Try to use a parent type name from x-mef-target extension in
schema. If not defined the fallback is to take 'model-name'
-f, --force-override
This option may occur a maximum of 1 times
-m , --model-name
Model which will be hosting product specific extensions (e.g.
MEFProductConfiguration)
-o , --output
Output file name. Throws exception if file exists.
This option may occur a maximum of 1 times
--sorted
sort data types in a lexical order
This option may occur a maximum of 1 times
```
### Usage example for Sonata
Assumption is that this command is run from any directory. `-d` parameter points to root of the schema directory.
In this example this directory hosts
```shell script
java -jar blender-all-in.jar merge \
-d ${rootSchemaDirectory} \
-b accessEline\accessElineOvc.yaml \
-b carrierEthernetOperatorUni\carrierEthernetOperatorUni.yaml
```
### Usage example for Legato
Assumption is that this command is run from the schema directory. You could also use `-d` parameter to point to
different directory as in the example above.
```shell script
java -jar blender-all-in.jar merge \
-b carrierEthernetOvc.yaml \
-b carrierEthernetSubscriberUni.yaml
```