How kbuntrock/openapi-maven-plugin works
Main Components
• Maven Plugin Core – This is the heart of the project and is implemented in the “openapi-maven-plugin” directory. Core classes include the DocumentationMojo (the Maven goal), ApiResourceScanner, and JavaClassAnalyser. These components are responsible for scanning the compiled classes and source code.
• Configuration Management – The plugin supports extensive configuration options. Look into the “configuration” directory where classes like ApiConfiguration, CommonApiConfiguration, EnumConfig, etc., reside. This component is in charge of determining which classes/methods to include or ignore, as well as processing additional documentation data.
• Parsing and Conversion – There are dedicated packages for parsing inputs: “parser” (with JsonParserUtils, YamlParserUtils) and “javadoc” (with the JavadocParser and associated classes). These modules extract and process annotations, Javadoc comments, and then translate them into structured intermediate models found in the “model” package.
• Reflection Handling – The package “reflection” includes utility classes (GenericArrayTypeImpl, ParameterizedTypeImpl, etc.) that support the accurate determination of generic types, which is important for mapping ‘real’ parameter and response types.
• YAML/DOC Generation – After processing, the “yaml” package (including YamlWriter and the model classes for OpenAPI components like Schema, Info, Operation, etc.) is used to generate the final OpenAPI documentation in YAML or JSON format.
• Testing / Integration – There is a separate “integration-tests” directory that contains sample REST controllers (e.g., in the nominal test cases across various jdk versions) to validate the functionality of the plugin. This module integrates the usage of the plugin with test repositories and ensures the output OpenAPI documentation is correct.
Relationships and Interactions
• The Maven Plugin Core (via DocumentationMojo) is invoked during the build phase. It first loads the configuration settings (Configuration Management) from the project’s pom.xml.
• The ApiResourceScanner then kicks off the scanning process in the compiled classes. It delegates to specialized readers (for instance, SpringMvcReader, JavaxRsReader, JakartaRsReader) via the configuration library reader modules.
• The JavaClassAnalyser works with Reflection components to interpret the class and method signatures. It also calls on the JavadocParser to extract any relevant documentation from source comments.
• The intermediate models (data objects like Endpoint, DataObject, Tag, etc.) built during scanning are then passed to the YAML generation modules, where YamlWriter converts these models into proper OpenAPI definitions.
• The integration tests validate these interactions by providing specific test cases and expected outputs for different JDK environments.
Architectural Patterns and Design Principles
• Modularity: Each major functionality (configuration, scanning, parsing, reflection, documentation generation) is implemented in its own set of packages. This separation of concerns facilitates easier maintenance and extension.
• Plugin Architecture: It is built as a Maven plugin with a clear separation between build configuration and runtime behavior.
• Reusability: The design leverages common libraries and utilities (utils package for file handling, logging, etc.), enabling reuse across different parts of the plugin.
• Extensibility: The use of “white list” and “black list” filtering, as well as configuration libraries for annotation reading, shows that the project was built to allow for additional customization and integration points.
Relevant Technologies and Frameworks
• Java (with support across multiple versions).
• Maven (as the build system and as the mechanism for plugin integration).
• REST-related frameworks (support for Spring MVC, Javax RS, Jakarta RS annotations).
• Tools for YAML/JSON processing.
• Reflection, Annotation Processing, and Javadoc parsing utilities.