Enhanced Schema Configuration via Properties File and Template Generation

[anton-tkachenko]

** Is your feature request related to a problem? Please describe. **

I have a need to configure most text fields within a schema through a properties file rather than using annotations. This will offer more flexibility and control, including:

Reliance on conventional property naming instead of specifying property values in the @Schema annotation.
Control over various text fields like endpoint summaries (using operation IDs), API descriptions, model names, titles, descriptions, and examples.
The current approach using springdoc.api-docs.resolve-schema-properties is limited, and I want a more comprehensive solution.

I can't modify the generated schema directly because it's not the source of truth, and any code changes would disrupt my customizations.

** Describe the solution you'd like **

I propose the addition of a feature that generates a "template" properties file that corresponds to the project's schema. This template can then be easily populated with the desired content, removing the need to guess conventions when configuring the schema properties.

** Describe alternatives you've considered **

I've explored potential alternatives, but I haven't found any built-in solutions that meet my requirements. To address this need, I plan to create an OpenApiCustomizer for this purpose. My ultimate goal is to contribute this solution to the springdoc project. However, I would greatly appreciate feedback and ideas from the community to ensure a better alignment with the project's goals.

Example Properties:

Let's consider a scenario where you want to configure the API documentation for a RESTful service. You might define properties like these in the template properties file:

properties

# API Description
springdoc.api-docs.description=This is a sample API for demonstration purposes.

# Model Information
springdoc.model.user.name=User
springdoc.model.user.title=User Model
springdoc.model.user.description=This model represents a user entity.
springdoc.model.user.example=...

# Endpoint Information
springdoc.endpoint.getUsers.summary=Get a list of users
springdoc.endpoint.getUsers.description=This endpoint retrieves a list of all users.
springdoc.endpoint.getUserById.summary=Get user by ID
springdoc.endpoint.getUserById.description=Retrieve a user by their unique identifier.

These properties allow you to control various aspects of the API documentation, including descriptions, model details, and endpoint summaries.

Sample YAML Schema:

Suppose you have the following sample YAML schema for the API:

yaml
Copy code
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
  description: This is a sample API for demonstration purposes.

paths:
  /users:
    get:
      summary: Get a list of users
      description: This endpoint retrieves a list of all users.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

  /users/{userId}:
    get:
      summary: Get user by ID
      description: Retrieve a user by their unique identifier
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string

In this sample YAML schema, the properties from the properties file are used to populate the info section for the API description, configure the User model, and set the summaries and descriptions for the /users and /users/{userId} endpoints.

By using the properties file to customize the schema, you can easily maintain and modify the documentation without changing the source code.

[bnasslahsen]

@anton-tkachenko,

There is no current plans to support this feature.
If you feel it useful for the community, feel free to propose a PR.