feat(openapi): add generation for extension api

Author: kpanot

packages/@ama-openapi/create/README.md

@@ -59,14 +59,26 @@ my-openapi-project/
 └── renovate.json
 ```
 
-> [!NOTE]
-> The package includes several template files that are customized during project generation:
->
-> - **API specifications**: Example OpenAPI YAML files
-> - **Configuration files**: Project-specific configurations
-> - **Development environment**: VS Code settings and extensions
-> - **Package management**: Pre-configured `package.json` file with common scripts
-> - **Renovate Configuration**: Extends the [@ama-openapi/core preset] package (<https://github.com/AmadeusITGroup/otter/tree/main/packages/@ama-openapi/core/renovate/default.json>)
+### Design Exntension Project
+
+Create a new [OpenAPI](https://www.openapis.org/) design project extension via the following command :
+
+```shell
+npm create @ama-openapi extension <project-name> -- [options]
+```
+
+The following options are available:
+
+| Options | Default Value | Description |
+| --- | --- | --- |
+| `--target`, `-t` | `.` | Target directory where files will be generated. |
+| `--dependency-base-spec`, `-b` | - | Name of the NPM artifact to use as the dependency base specification (e.g. @my-org/specification). |
+
+The command will generate a directory with the same structure of the `design` command but will setup the repository to prepare the generation of 3 specification:
+
+- `base` specification which is extended by the current specification
+- `extension` specification bundling only the specification defined in the current project
+- `merge` specification which is the merge of the `base` with `extension` specification.
 
 ## Integration
 

packages/@ama-openapi/create/src/generate-design.ts

@@ -0,0 +1,26 @@
+import {
+  OUTPUT_DIRECTORY,
+  // eslint-disable-next-line import/no-unresolved -- Cannot resolve mjs file in current setup (see #3738)
+} from '@ama-openapi/core';
+import {
+  type CreateOptions,
+  generateTemplate,
+} from './generate-template';
+
+/**
+ * Generate design project
+ * @param target
+ * @param packageName
+ * @param version
+ */
+export const generateDesign = (target: string, packageName: string, version: string) => {
+  const options: CreateOptions = {
+    target,
+    externalModelPath: OUTPUT_DIRECTORY,
+    version,
+    templateDirectory: 'design',
+    packageName,
+    logger: console
+  };
+  return generateTemplate(options);
+};

packages/@ama-openapi/create/src/generate-extension.ts

@@ -0,0 +1,58 @@
+import {
+  readFile,
+  writeFile,
+} from 'node:fs/promises';
+import {
+  resolve,
+} from 'node:path';
+import {
+  OUTPUT_DIRECTORY,
+  // eslint-disable-next-line import/no-unresolved -- Cannot resolve mjs file in current setup (see #3738)
+} from '@ama-openapi/core';
+import {
+  type CreateOptions,
+  generateTemplate,
+} from './generate-template';
+
+/**
+ * Generate extension project
+ * @param target
+ * @param packageName
+ * @param version
+ * @param dependencyBaseSpec
+ */
+export const generateExtension = async (target: string, packageName: string, version: string, dependencyBaseSpec?: string) => {
+  const options = {
+    target,
+    externalModelPath: OUTPUT_DIRECTORY,
+    version,
+    dependencyBaseSpec,
+    packageName,
+    logger: console
+  } as const satisfies Partial<CreateOptions>;
+  await generateTemplate({ ...options, templateDirectory: 'design' });
+  await generateTemplate({ ...options, templateDirectory: 'design-extension' });
+
+  const scripts = {
+    build: 'redocly bundle && npm run build:merge',
+    'build:base': 'redocly bundle base',
+    'build:extension': 'redocly bundle server',
+    'build:merge': 'redocly bundle filter-client && redocly join filtered-client server -o ./bundle/specification.yaml',
+    'retrieve-externals': 'ama-openapi install',
+    'watch:retrieve-externals': 'ama-openapi watch',
+    postinstall: 'ama-openapi install'
+  };
+
+  const packageJsonPath = resolve(target, 'package.json');
+  return writeFile(
+    packageJsonPath,
+    JSON.stringify(
+      {
+        ...JSON.parse(await readFile(packageJsonPath, { encoding: 'utf8' })),
+        ...scripts
+      },
+      null,
+      2
+    )
+  );
+};

packages/@ama-openapi/create/src/generate-template.ts

@@ -18,7 +18,7 @@ import {
   sync,
 } from 'globby';
 
-type Templates = 'design';
+type Templates = 'design' | 'design-extension';
 
 /**
  * Options for template generation
@@ -34,6 +34,8 @@ export interface CreateOptions {
   packageName: string;
   /** Name of the template directory */
   templateDirectory: Templates;
+  /** Dependency base specification */
+  dependencyBaseSpec?: string;
   /** Logger */
   logger: typeof console;
 }

packages/@ama-openapi/create/src/index.ts

@@ -6,10 +6,6 @@ import {
 import {
   resolve,
 } from 'node:path';
-import {
-  OUTPUT_DIRECTORY,
-  // eslint-disable-next-line import/no-unresolved -- Cannot resolve mjs file in current setup (see #3738)
-} from '@ama-openapi/core';
 import type {
   PackageJson,
 } from 'type-fest';
@@ -18,9 +14,11 @@ import {
   hideBin,
 } from 'yargs/helpers';
 import {
-  type CreateOptions,
-  generateTemplate,
-} from './generate-template';
+  generateDesign,
+} from './generate-design';
+import {
+  generateExtension,
+} from './generate-extension';
 
 void (async () => {
   const version = (JSON.parse(await fs.readFile(resolve(__dirname, '..', 'package.json'), { encoding: 'utf8' })) as PackageJson).version!;
@@ -38,14 +36,23 @@ void (async () => {
         describe: 'Name of the artifact / package to generate'
       });
     }, async (argv) => {
-      const options: CreateOptions = {
-        target: argv.target,
-        externalModelPath: OUTPUT_DIRECTORY,
-        version,
-        packageName: argv.name,
-        logger: console
-      };
-      await generateTemplate(options);
+      await generateDesign(argv.target, argv.name, version);
+    })
+    .command('extension <name>', 'Name of the artifact / package to generate', (y) => {
+      return y
+        .positional('name', {
+          type: 'string',
+          demandOption: true,
+          describe: 'Name of the artifact / package to generate'
+        })
+        .option('dependencyBaseSpec', {
+          type: 'string',
+          alias: 'b',
+          demandOption: false,
+          describe: 'Name of the NPM artifact to use as the dependency base specification (e.g. @my-org/specification)'
+        });
+    }, async (argv) => {
+      await generateExtension(argv.target, argv.name, version, argv.dependencyBaseSpec);
     })
     .version(version)
     .alias('h', 'help')

packages/@ama-openapi/create/templates/design-extension/.gitignore.template

@@ -0,0 +1,13 @@
+<% if (standardGitignoreNode) { %>
+<%- standardGitignoreNode %>
+<% } else { %>
+# Dependency directory
+node_modules/
+<% } %>
+
+# External models directory
+/<%- externalModelPath %>
+
+# Bundle specifications directory
+/tmp
+/bundle

packages/@ama-openapi/create/templates/design-extension/README.md.template

@@ -0,0 +1,56 @@
+# <%- packageName %>
+
+This package exposes 3 different [OpenApi specifications](https://swagger.io/specification/) which can be used to use to generate an SDK or be referred in another specification.
+
+- `<%- packageName %>/bundle/base.yam;`: The core the extension is based on.
+- `<%- packageName %>/bundle/extension.yaml`: The extension specification which contains only the new endpoints .
+- `<%- packageName %>/bundle/specification.yaml`: The merged specification of the base and the extension
+
+## How to work on it
+
+**Recommendations:**
+
+- Code editor [Visual Studio Code](https://code.visualstudio.com/) with the recommended extension (proposed on start).
+- [NodeJs](https://nodejs.org/) with a odd [LTS (or latest) version](https://nodejs.org/en/about/previous-releases).
+
+**Setup:**
+
+```shell
+npm install
+```
+
+### Add dependency
+
+```shell
+npm install <artifact_name>
+```
+
+and refer to its models via config in the [manifest](https://github.com/AmadeusITGroup/otter/tree/main/docs/openapi/MANIFEST_CONFIGURATION.md):
+
+```yaml
+models:
+  <artifact_name>:
+    - models/first-model.yaml
+    - models/second-model.yaml
+```
+
+> [!NOTE]
+> The complete documentation is available on [Dependency concept documentation](https://github.com/AmadeusITGroup/otter/tree/main/docs/openapi/DEPENDENCY_RESOLUTION_CONCEPT.md).
+
+## Repository structure
+
+The current repository has the following structure:
+
+```text
+<%- projectFolder %>/
+├── .vscode/                  # VsCode options and recommended extension
+├── apis/                     # List of the Apis to bundle in the final specification
+├── models/                   # Models to be referred locally and shared
+├── responses/                # List of responses used in the APIs
+├── .gitignore
+├── openapi.manifest.yaml
+├── package.json
+├── redocly.yaml
+├── README.md
+└── renovate.json
+```

packages/@ama-openapi/create/templates/design-extension/redocly.yaml.template

@@ -0,0 +1,29 @@
+extends:
+  - recommended
+
+plugins:
+  - '@ama-openapi/redocly-plugin'
+
+apis:
+  # The base API
+  base:
+    root: ./node_modules/<%- dependencyBaseSpec || '@example/package' %>/bundle/specification.yaml
+    output: bundle/base.yaml
+
+  # The API of the extension
+  extension@v1:
+    root: apis/example.v1.yaml
+    output: bundle/extension.yaml
+
+  # This API is used to filter out the extended endpooints of the base API
+  filter-base:
+    root: ./node_modules/<%- dependencyBaseSpec || '@example/package' %>/bundle/specification.yaml
+    output: ./tmp/filtered-dapi.yaml
+    decorators:
+      filter-out:
+        property: operationId
+        value: [] # Array of operationIds to filter
+
+  # This filtered base API
+  filtered-client:
+    root: ./tmp/filtered-dapi.yaml

packages/@ama-openapi/create/templates/design/README.md.template

@@ -4,7 +4,7 @@ This package exposes [OpenApi specification](https://swagger.io/specification/)
 
 ## How to work on it
 
-**Requirements:**
+**Recommendations:**
 
 - Code editor [Visual Studio Code](https://code.visualstudio.com/) with the recommended extension (proposed on start).
 - [NodeJs](https://nodejs.org/) with a odd [LTS (or latest) version](https://nodejs.org/en/about/previous-releases).