@visulima/jsdoc-open-api 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## @visulima/jsdoc-open-api [1.0.3](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@1.0.2...@visulima/jsdoc-open-api@1.0.3) (2022-10-27)
+
+
+### Bug Fixes
+
+* fixed package.json files paths ([0d21e94](https://github.com/visulima/visulima/commit/0d21e94a75e9518f7b87293706615d8fb280095c))
+
+
+
+### Dependencies
+
+* **@visulima/readdir:** upgraded to 1.1.1
+
 ## @visulima/jsdoc-open-api [1.0.2](https://github.com/visulima/visulima/compare/@visulima/jsdoc-open-api@1.0.1...@visulima/jsdoc-open-api@1.0.2) (2022-10-27)
 
 

package/README.md

@@ -47,7 +47,7 @@ Choose the syntax you want to use for your OpenAPI definitions:
 
 ![choose the syntax](./assets/swagger-difference.png)
 
-CLI:
+### CLI:
 
 ```bash
 # This generate the .openapirc.js config file, this command is only needed on the first run
@@ -57,6 +57,96 @@ jsdoc-open-api init
 jsdoc-open-api generate src/
 ```
 
+### As Next.js webpack plugin:
+
+#### with-open-api.js
+```js
+
+const path = require("node:path");
+const fs = require("node:fs");
+const { SwaggerCompilerPlugin } = require("@visulima/jsdoc-open-api");
+
+/**
+ * @param definition {import('@visulima/jsdoc-open-api').SwaggerDefinition}
+ * @param sources {string[]}
+ * @param verbose {boolean}
+ * @param output {string}
+ *
+ * @returns {function(*): *&{webpack: function(Configuration, *): (Configuration)}}
+ */
+const withOpenApi = ({ definition, sources, verbose, output = "swagger/swagger.json" }) => (nextConfig) => {
+    return {
+        ...nextConfig,
+        webpack: (config, options) => {
+            if (!options.isServer) {
+                return config;
+            }
+
+            if (output.startsWith("/")) {
+                output = output.slice(1);
+            }
+
+            if (!output.endsWith(".json")) {
+                throw new Error("The output path must end with .json");
+            }
+
+            // eslint-disable-next-line no-param-reassign
+            config = {
+                ...config,
+                plugins: [
+                // @ts-ignore
+                    ...config.plugins,
+                    new SwaggerCompilerPlugin(`${options.dir}/${output}`, sources.map((source) => {
+                        const combinedPath = path.join(options.dir, source.replace("./", ""));
+
+                        // Check if the path is a directory
+                        fs.lstatSync(combinedPath).isDirectory();
+
+                        return combinedPath;
+                    }), definition, { verbose }),
+                ],
+            };
+
+            if (typeof nextConfig.webpack === "function") {
+                return nextConfig.webpack(config, options);
+            }
+
+            return config;
+        },
+    };
+};
+
+module.exports = withOpenApi;
+```
+
+#### next.config.js
+```js
+const withOpenApi = require("./with-open-api");
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+    reactStrictMode: true,
+    swcMinify: true,
+    env: {
+        NEXT_PUBLIC_APP_ORIGIN: process.env.VERCEL_URL || "http://localhost:3001",
+    }
+};
+
+module.exports = withOpenApi({
+    definition: {
+        openapi: "3.0.0",
+        info: {
+            title: "My API",
+            version: "1.0.0",
+        },
+    },
+    sources: [
+         "pages/api",
+    ],
+    verbose: false, // default is false
+})(nextConfig);
+```
+
 ## OpenApi yaml syntax
 
 The library will take the contents of @openapi (or @swagger):

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@visulima/jsdoc-open-api",
-    "version": "1.0.2",
+    "version": "1.0.3",
     "description": "Generates swagger doc based on JSDoc.",
     "keywords": [
         "visulima",
@@ -53,7 +53,8 @@
         "jsdoc-open-api": "./bin/index.js"
     },
     "files": [
-        "dist/**",
+        "src",
+        "dist",
         "README.md",
         "CHANGELOG.md",
         "LICENSE.md"
@@ -70,7 +71,7 @@
     },
     "dependencies": {
         "@apidevtools/swagger-parser": "^10.1.0",
-        "@visulima/readdir": "1.1.0",
+        "@visulima/readdir": "1.1.1",
         "cli-progress": "^3.11.2",
         "commander": "^9.4.1",
         "comment-parser": "^1.3.1",

package/src/exported.d.ts

@@ -0,0 +1,266 @@
+declare function openapi(options?: ParserOptions): OpenApiObject;
+
+export default openapi;
+
+export interface ParserOptions {
+    cwd: string;
+    extension?: string[];
+    include?: string[];
+    exclude?: string[];
+    excludeNodeModules?: boolean;
+    verbose?: boolean;
+}
+
+export interface BaseDefinition {
+    openapi: string;
+    info: InfoObject;
+    servers?: ServerObject[];
+    paths?: PathsObject;
+    components?: ComponentsObject;
+    security?: SecurityRequirementObject[];
+    tags?: TagObject[];
+    externalDocs?: ExternalDocumentationObject;
+}
+
+export interface OpenApiObject extends BaseDefinition {
+    paths: PathsObject;
+}
+
+export interface InfoObject {
+    title: string;
+    version: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: ContactObject;
+    license?: LicenseObject;
+}
+
+export interface ContactObject {
+    name?: string;
+    url?: string;
+    email?: string;
+}
+
+export interface LicenseObject {
+    name: string;
+    url?: string;
+}
+
+export interface ServerObject {
+    url: string;
+    description?: string;
+    variables?: Map<ServerVariable>;
+}
+
+export interface ServerVariable {
+    default: string;
+    enum?: string[];
+    description?: string;
+}
+
+export interface ComponentsObject {
+    schemas?: Map<SchemaObject | ReferenceObject>;
+    responses?: Map<ResponseObject | ReferenceObject>;
+    parameters?: Map<ParameterObject | ReferenceObject>;
+    examples?: Map<ExampleObject | ReferenceObject>;
+    requestBodies?: Map<RequestBodyObject | ReferenceObject>;
+    headers?: Map<HeaderObject | ReferenceObject>;
+    securitySchemes?: Map<
+    ApiKeySecuritySchemeObject | HttpSecuritySchemeObject | Oauth2SecuritySchemeObject | OpenIdConnectSecuritySchemeObject | ReferenceObject
+    >;
+    links?: Map<LinkObject | ReferenceObject>;
+    callbacks?: Map<CallbackObject | ReferenceObject>;
+}
+
+export interface PathsObject {
+    [path: string]: PathItemObject;
+}
+
+export interface PathItemObject {
+    $ref?: string;
+    summary?: string;
+    description?: string;
+    get?: OperationObject;
+    put?: OperationObject;
+    post?: OperationObject;
+    delete?: OperationObject;
+    options?: OperationObject;
+    head?: OperationObject;
+    patch?: OperationObject;
+    trace?: OperationObject;
+    servers?: ServerObject[];
+    parameters?: (ParameterObject | ReferenceObject)[];
+}
+
+export interface OperationObject {
+    responses: ResponsesObject;
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+    operationId?: string;
+    parameters?: (ParameterObject | ReferenceObject)[];
+    requestBody?: RequestBodyObject | ReferenceObject;
+    callbacks?: Map<CallbackObject | ReferenceObject>;
+    deprecated?: boolean;
+    security?: SecurityRequirementObject[];
+    servers?: ServerObject[];
+}
+
+export interface ExternalDocumentationObject {
+    url: string;
+    description?: string;
+}
+
+export interface ParameterObject {
+    name: string;
+    in: string;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    //
+    style?: string;
+    explode?: string;
+    allowReserved?: boolean;
+    schema?: SchemaObject | ReferenceObject;
+    example?: any;
+    examples?: Map<ExampleObject | ReferenceObject>;
+    //
+    content?: Map<MediaTypeObject>;
+    // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+    // pipeDelimited and deepObject
+}
+
+export interface RequestBodyObject {
+    content: Map<MediaTypeObject>;
+    description?: string;
+    required?: boolean;
+}
+
+export interface MediaTypeObject {
+    schema?: SchemaObject | ReferenceObject;
+    example?: any;
+    examples?: Map<ExampleObject | ReferenceObject>;
+    encoding?: Map<EncodingObject>;
+}
+
+export interface EncodingObject {
+    contentType?: string;
+    headers?: Map<HeaderObject | ReferenceObject>;
+    style?: string;
+    explode?: boolean;
+    allowReserved?: boolean;
+}
+
+export interface ResponsesObject {
+    [code: string]: ResponseObject | ReferenceObject;
+}
+
+export interface ResponseObject {
+    description: string;
+    headers?: Map<HeaderObject | ReferenceObject>;
+    content?: Map<MediaTypeObject>;
+    links?: Map<LinkObject | ReferenceObject>;
+}
+
+export interface CallbackObject {
+    [expression: string]: PathItemObject;
+}
+
+export interface ExampleObject {
+    summary?: string;
+    description?: string;
+    value?: any;
+    externalValue?: string;
+}
+
+export interface LinkObject {
+    operationRef?: string;
+    operationId?: string;
+    parameters?: Map<any>;
+    requestBody?: any;
+    description?: string;
+    server?: ServerObject;
+}
+
+export interface HeaderObject {
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    allowEmptyValue?: boolean;
+    //
+    style?: string;
+    explode?: string;
+    allowReserved?: boolean;
+    schema?: SchemaObject | ReferenceObject;
+    example?: any;
+    examples?: Map<ExampleObject | ReferenceObject>;
+    //
+    content?: Map<MediaTypeObject>;
+    // ignoring stylings: matrix, label, form, simple, spaceDelimited,
+    // pipeDelimited and deepObject
+}
+
+export interface TagObject {
+    name: string;
+    description?: string;
+    externalDocs?: ExternalDocumentationObject;
+}
+
+export interface ReferenceObject {
+    $ref: string;
+}
+
+// TODO: this could be expanded on.
+export interface SchemaObject {
+    [key: string]: any;
+}
+
+export interface ApiKeySecuritySchemeObject {
+    type: string;
+    description?: string;
+    name: string;
+    in: string;
+}
+
+export interface HttpSecuritySchemeObject {
+    type: string;
+    description?: string;
+    scheme: string;
+    bearerFormat?: string;
+}
+
+export interface Oauth2SecuritySchemeObject {
+    type: string;
+    description?: string;
+    flows: OAuthFlowsObject;
+}
+
+export interface OpenIdConnectSecuritySchemeObject {
+    type: string;
+    description?: string;
+    openIdConnectUrl: string;
+}
+
+export interface OAuthFlowsObject {
+    implicit?: OAuthFlowObject;
+    password?: OAuthFlowObject;
+    clientCredentials?: OAuthFlowObject;
+    authorizationCode?: OAuthFlowObject;
+}
+
+export interface OAuthFlowObject {
+    authorizationUrl?: string; // required for some?
+    tokenUrl?: string; // required for some?
+    refreshUrl: string;
+    scopes: Map<string>;
+}
+
+export interface SecurityRequirementObject {
+    [name: string]: string[];
+}
+
+export interface Map<T> {
+    [key: string]: T;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { default as SpecBuilder } from "./spec-builder";
+export { default as parseFile } from "./parse-file";
+export { default as yamlLoc } from "./util/yaml-loc";
+export type { BaseDefinition, OpenApiObject } from "./exported";
+export { default as SwaggerCompilerPlugin } from "./webpack/swagger-compiler-plugin";
+export { default as jsDocumentCommentsToOpenApi } from "./jsdoc/comments-to-open-api";
+export { default as swaggerJsDocumentCommentsToOpenApi } from "./swagger-jsdoc/comments-to-open-api";