Documentation
    Preparing search index...

    Interface ISwaggerConfig

    Building swagger.json is also possible.

    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.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods