Create jsdoc

.github/workflows/build.yaml

@@ -1,20 +1,23 @@
-name: Test, Build and Deploy Example to GitHub-Pages
+name: Test and Build and Deploy Example to GitHub-Pages
 on: [ push ]
 permissions:
   contents: read
   pages: write
   id-token: write
 jobs:
   Build:
+    name: Build and Test the application
     runs-on: ubuntu-latest
     steps:
       # Setup stuff
-      - uses: actions/checkout@v4
-      - run: corepack enable
-      - uses: actions/setup-node@v4
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Enable corepack
+        run: corepack enable
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
           node-version: 21
-          registry-url: 'https://registry.npmjs.org'
           cache: 'yarn'
 
       # Check and build project
@@ -23,15 +26,66 @@ jobs:
       - run: yarn build
       - run: yarn test
 
-      # Generate example
-      - run: yarn workspace example generate:ci
-      - uses: actions/upload-pages-artifact@v3
+      - name: Store dist folder
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          if-no-files-found: error
+          retention-days: 1
+          overwrite: false
+
+  Example:
+    name: Generate Example-Documentation
+    runs-on: ubuntu-latest
+    needs: Build
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Enable corepack
+        run: corepack enable
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 21
+          cache: 'yarn'
+      - name: Download dist folder
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Generate documentation for example
+        run: yarn workspace example generate:ci
+      - name: Upload generated documentation to github pages
+        uses: actions/upload-pages-artifact@v3
         with:
           path: "./example/out"
       - uses: actions/deploy-pages@v4
 
-      # publish library
-      - run: yarn npm publish
-        if: github.ref == 'refs/heads/main'
+  Publish:
+    name: Publish to NPM registry
+    runs-on: ubuntu-latest
+    needs: Build
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Enable corepack
+        run: corepack enable
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 21
+          cache: 'yarn'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Download dist folder
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish
+        run: yarn npm publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

example/main.js

@@ -3,8 +3,6 @@ const { run, openApiPlugin, javaPlugin, htmlWriter, markdownWriter, defaultReade
 const inputDir = path.join(__dirname, '/input')
 const outputDir = path.join(__dirname, '/out')
 
-// TODO: Move GitHub-Pages template to here
-
 run({
   reader: defaultReader(inputDir),
   plugins: [openApiPlugin(outputDir), javaPlugin(outputDir)],

lib/src/Run.ts

@@ -2,26 +2,38 @@ import { defaultReader } from './reader/DefaultReader'
 import { htmlWriter } from './writer/html/HtmlWriter'
 import { type RunOptions } from './RunOptions'
 
-// TODO: Document Run and Options
-export async function run (options?: RunOptions): Promise<void> {
-  const reader = options?.reader ?? defaultReader('./input')
-  const plugins = options?.plugins ?? []
-  const writers = options?.writers ?? [htmlWriter('./out')]
+/**
+ * Run domain-schema-documentation with the given options.
+ * @param optionsOrUndefined Options or default if not given
+ * @returns {Promise<void>} Promise that resolves when the run is finished
+ * @see RunOptions
+ */
+export async function run (optionsOrUndefined?: Partial<RunOptions>): Promise<void> {
+  const options = applyDefaults(optionsOrUndefined)
 
-  let model = await reader()
+  // Read the input model
+  let model = await options.reader()
 
   // Update model with plugins, must be executed in sequence
-  for (const plugin of plugins) {
+  for (const plugin of options.plugins) {
     model = await plugin.updateModel?.(model) ?? model
   }
 
   // Validate model with plugins, can be executed in parallel
-  const errorMap = await Promise.all(plugins.map(async p => await p.validate?.(model) ?? []))
+  const errorMap = await Promise.all(options.plugins.map(async p => await p.validate?.(model) ?? []))
   const errors = errorMap.flatMap(e => e)
 
   // Generate output with plugins, can be executed in parallel
-  await Promise.all(plugins.map(async p => await p.generateOutput?.(model)))
+  await Promise.all(options.plugins.map(async p => await p.generateOutput?.(model)))
 
   // Write output, can be executed in parallel
-  await Promise.all(writers.map(async w => { await w(model, errors) }))
+  await Promise.all(options.writers.map(async w => { await w(model, errors) }))
+}
+
+function applyDefaults (options?: Partial<RunOptions>): RunOptions {
+  return {
+    reader: options?.reader ?? defaultReader('./input'),
+    plugins: options?.plugins ?? [],
+    writers: options?.writers ?? [htmlWriter('./out')]
+  }
 }

lib/src/RunOptions.ts

@@ -2,9 +2,28 @@ import { type Plugin } from './plugin/Plugin'
 import { type Writer } from './writer/Writer'
 import { type Reader } from './reader/Reader'
 
-// TODO: Document Run and Options
+/**
+ * Options for the run function.
+ */
 export interface RunOptions {
-  plugins?: Plugin[]
-  reader?: Reader
-  writers?: Writer[]
+  /**
+   * Reader to use. Must implement the Reader interface.
+   * If not defined, defaultReader is used on folder './input'
+   * @see reader/Reader
+   * @see reader/DefaultReader
+   */
+  reader: Reader
+  /**
+   * Plugins to use. Must implement the Plugin interface.
+   * If not defined, no plugins are used.
+   * @see plugin/Plugin
+   */
+  plugins: Plugin[]
+  /**
+   * Writers to use. Must implement the Writer interface.
+   * If not defined, htmlWriter is used on folder './out'
+   * @see writer/Writer
+   * @see writer/html/HtmlWriter
+   */
+  writers: Writer[]
 }

lib/src/index.ts

@@ -1,20 +1,20 @@
+export * from './Run'
+export * from './RunOptions'
 export * from './plugin/Plugin'
 export * from './plugin/openapi/OpenApiPlugin'
 export * from './plugin/java/JavaPlugin'
-export * from './reader/Model'
 export * from './reader/DefaultReader'
+export * from './reader/DefaultReaderOptions'
 export * from './reader/InputNormalizer'
+export * from './reader/Model'
+export * from './reader/Reader'
 export * from './reader/helper/GetDependencies'
 export * from './reader/helper/GetType'
 export * from './reader/helper/InputHelper'
+export * from './writer/MermaidDiagramGenerator'
 export * from './writer/Writer'
 export * from './writer/WriterHelpers'
-export * from './writer/MermaidDiagramGenerator'
 export * from './writer/html/HtmlWriter'
+export * from './writer/html/HtmlWriterOptions'
 export * from './writer/markdown/MarkdownWriter'
-export * from './Run'
-export type { RunOptions } from './RunOptions'
-export type { HtmlWriterOptions } from './writer/html/HtmlWriterOptions'
-export type { MarkdownWriterOptions } from './writer/markdown/MarkdownWriterOptions'
-export type { Reader } from './reader/Reader'
-export type { DefaultReaderOptions } from './reader/DefaultReaderOptions'
+export * from './writer/markdown/MarkdownWriterOptions'

lib/src/plugin/openapi/OpenApiPlugin.ts

@@ -37,7 +37,7 @@ async function validateOpenApiSpec (): Promise<VerificationError[]> {
 
 async function generateOpenApiSpecs (model: Model, outputFolder: string, options?: OpenApiPluginOptions): Promise<void> {
   await Promise.all(model.modules.map(async module => {
-    if (module.operations === undefined) return
+    // TODO: If no operations, skip
     const relativeFilename = path.join(module.$id, getFileName(module))
     const output = generateOpenApiSpec(model, module, options)
     const yamlOutput = yaml.stringify(output)
@@ -53,7 +53,8 @@ function generateOpenApiSpec (model: Model, module: Module, options?: OpenApiPlu
       description: module.description
     },
     servers: options?.servers?.map(server => ({ url: server })) ?? [],
-    paths: module.operations,
+    // TODO: Use operations from the input?
+    paths: {},
     components: {
       // TODO: Get all relevant schemas
       schemas: {},