Add option to hide URL Field element for an individual documentation block

[jerrens]

Feature request

I would like to include JSON schema and other 'general notes' areas in the generated API Docs page for users to view. I know normally stuff like schema examples would be defined and available in the details of a REST API using one of the @api*Example tags, or @apiDefine/@APIuse. However, there is other general information that I would like to include in the generated page, and then be able to provide links from other areas with See [Demo Object Schema](#api-Schema-DemoSchemaEntry) for details. Sometimes the details can be fairly long, and used in multiple places throughout the REST API. Using the @apiDefine/@APIuse feature does allow me to maintain one copy and use it in many places, but that large block is duplicated often in the generated page and just causes unnecessary "noise" everywhere that is only needed as a reference occasionally for the user.

If I were to include this information in the header or footer MD files, not only would those files get to be huge (since I can't define other MD files other than those two that I know of), but I also would not get the nice entries on the left navbar nor the ability to leverage the @apiversion functionality that comes with the @api blocks.

Today, this is what gets rendered:

What I would love to be able to have is:

(I simply added `display: none' to the HTML Element style in the browser)

If there was a way to disable the URL Path element, then I can leverage the rest of the tags to build what I need. One idea I had was if the @api tag supported attributes in place of or in addition to the path word.

/**
 * @api {schema} [hide] Demo Object
 * @apiVersion 2023.3.16
 * @apiName DemoSchemaEntry
 * @apiGroup Schema
 * @apiDescription Used to provide a section in the documentation that is not actually a REST API description
 *
 * @apiExample Demo Object Schema
 * {
 *      "SchemaVer": 20230316,
 *      "Name": "string", // Comment
 * }
 */

Or to leave room for future options, use key/value and CSV
@api {schema} [urlVisible=false,methodVisible=false] Demo Object

I know this is a bit of a hack with the @api tag, so I can understand if this feature is not pursued.

I'm not familiar with the inner workings of apidoc... maybe an easier, not-so-hackerish solution would be to provide an @apiConfig tag that allowed options to be defined/set on a per-block scope?

/**
 * @api {schema} / Demo Object
 * @apiVersion 2023.3.16
 * @apiName DemoSchemaEntry
 * @apiGroup Schema
 * @apiConfig
 *     urlVisible: false
 *     methodVisibile: false
 *     
 * @apiDescription Used to provide a section in the documentation that is not actually a REST API description
 *
 * @apiExample Demo Object Schema
 * {
 *      "SchemaVer": 20230316,
 *      "Name": "string", // Comment
 * }
 */

Thanks for the great tool and the consideration of this feature.

[NicolasCARPi]

Hello,

Please take into account that there is nobody available to maintain this library. See #1436.