Description
** 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.