Documentation
    Preparing search index...

    Interface ISwaggerConfig

    Building swagger.json is also possible.

    contracts/common.md#principled-implementation The output path is required and every other option refines the composed OpenAPI document before it is written.

    contracts/common.md#clear-and-simple-design A flat record of options with one callback.

    contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.

    contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.

    contracts/portability.md#os-neutral-implementation output is a native destination interpreted by path.parse/resolve in SwaggerGenerator; a nonempty extension denotes a file and otherwise the destination is a directory. Server URLs and operation paths retain protocol spelling independently of that filesystem boundary.

    interface ISwaggerConfig {
        additional?: boolean;
        beautify?: number | boolean;
        decompose?: boolean;
        info?: Partial<IInfo>;
        openapi?: "2.0" | "3.0" | "3.1" | "3.2";
        output: string;
        security?: Record<string, ISecurityScheme>;
        servers?: IServer[];
        tags?: ITag[];
        operationId?(
            props: {
                class: string;
                function: string;
                method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
                path: string;
            },
        ): string;
    }
    Index
    additional? beautify? decompose? info? openapi? output security? servers? tags?
    operationId?
    additional?: boolean

    Whether to include additional information or not.

    If configured to be true, those properties would be added into each API endpoint.

    • x-nestia-method: the HTTP method, such as "GET"
    • x-nestia-namespace: the SDK function's accessor, such as "bbs.articles.index"
    • x-nestia-jsDocTags: the JSDoc tags of the controller method
    false
    beautify?: number | boolean

    Whether to beautify JSON content or not.

    If you configure this property to be true, the swagger.json file would be beautified with indentation (2 spaces) and line breaks. If you configure numeric value instead, the indentation would be specified by the number.

    false
    decompose?: boolean

    Decompose query DTO.

    If you configure this property to be true, the query DTO would be decomposed into individual query parameters per each property. Otherwise you set it to be false, the query DTO would be one object type which contains all of query parameters, spread into its keys by style: form and explode: true.

    Swagger 2.0 has no object query parameter, and no OpenAPI version can spread an object into headers, so a query DTO of a Swagger 2.0 document and a headers DTO are decomposed regardless of this property.

    true
    info?: Partial<IInfo>

    API information.

    If omitted, package.json content would be used instead.

    openapi?: "2.0" | "3.0" | "3.1" | "3.2"

    OpenAPI version.

    If you configure this property to be 2.0, 3.0, or 3.1, the newly generated swagger.json file would follow the specified OpenAPI version, downgraded from the OpenAPI v3.2 specification.

    3.2
    output: string

    Response path of the swagger.json.

    If you've configured only directory, the file name would be the swagger.json. Otherwise you've configured the full path with file name and extension, the swagger.json file would be renamed to it.

    security?: Record<string, ISecurityScheme>

    Security schemes.

    When generating swagger.json file through nestia, if your controllers or theirs methods have a security key which is not enrolled in here property, it would be an error. So would an OAuth2 scope none of the scheme's flows declares, and, for an OpenAPI 3.0 or 2.0 document, scopes on a scheme other than OAuth2 or OpenID Connect, which those versions require to be empty; from 3.1 on they list role names.

    servers?: IServer[]

    List of server addresses.

    tags?: ITag[]

    List of tag names with description.

    It is possible to omit this property or skip some tag name even if the tag name is used in the API routes. In that case, the tag name would be used without description.

    Of course, if you've written a comment like @tag {name} {description}, you can entirely replace this property specification.

    • Operation ID generator.

      Parameters

      • props: {
            class: string;
            function: string;
            method: "HEAD" | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
            path: string;
        }

        Properties of the API endpoint.

      Returns string

      Operation ID.

      contracts/common.md#principled-implementation An explicit

      tag takes precedence; otherwise this callback receives the four identifying facts once for the composed operation and supplies its identifier.

      contracts/common.md#clear-and-simple-design One optional callback with a single argument object.

      contracts/common.md#prohibited-implementation-shortcuts It is a caller-supplied function and nothing about a particular naming scheme is built in.

      contracts/common.md#meaningful-documentation The comment documents the arguments and the result.

      contracts/portability.md#os-neutral-implementation This callback receives HTTP endpoint identity and returns an OpenAPI identifier; it owns no native pathname or process boundary.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods