Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
134 lines (99 loc) · 4.4 KB

CONTRIBUTING.md

File metadata and controls

134 lines (99 loc) · 4.4 KB

Contributing to OpenAPI Maven Plugin

First off, thank you for considering contributing! 🙌
Contributions help make this project better for everyone.

We welcome all kinds of contributions:

  • 🐛 Bug reports
  • 💡 Feature requests
  • 🛠️ Code improvements
  • 📝 Documentation updates

📌 How to Contribute

1. Fork & Clone

git clone git@github.com:kbuntrock/openapi-maven-plugin.git
cd openapi-maven-plugin

2. Create a Branch

git checkout -b feature/my-awesome-feature

3. Make Changes

  • The source code of the plugin stricly speaking is located in the openapi-maven-plugin sub-folder
  • Follow the Coding Guidelines (see below)
  • Keep commits atomic and messages clear

4. Format your code

This project uses the Eclipse formatter to standardize the code style. However, it is by no means necessary to use Eclipse to work on this project, and several approaches are available to format the source code according to the project’s conventions.

With Maven

You can use maven to format or verify that your code respect the project formalism:

# Formatting:
mvn formatter:format

# Or validating
mvn formatter:validate

With IntelliJ

You can use this nice plugin to use the Eclipse formatter with Jetbrain's IDE : https://github.com/krasa/EclipseCodeFormatter#instructions

The formatter configuration is located in openapi-maven-plugin/eclipse-formatter.xml.

With Eclipse

The formatter configuration is located in openapi-maven-plugin/eclipse-formatter.xml.

5. Run Tests
We use Maven for build and test automation:

# In the openapi-maven-plugin sub-folder:
mvn clean verify

6. Submit a Pull Request

  • Push your branch and open a PR against the dev branch.
  • Make sure your PR description explains what and why clearly.

🐛 Reporting Issues

  • Search the issue tracker first
  • If no existing issue matches, open a new one and include:
    • Steps to reproduce
    • Expected behavior
    • Actual behavior
    • Environment (JDK version, Maven version, OS)

💡 Feature Requests

We welcome ideas! When proposing a feature, please include:

  • Motivation (what problem it solves)
  • Example use cases
  • Suggested implementation (if any)

🧑‍💻 Coding Guidelines

  • Language: Java 8+ (compatible with JDK 8–21).
  • Style: Follow standard Java conventions / Format your code with the provided methods.
  • Tests: Add unit/integration tests for new functionality.
  • Code documentation: Update Javadoc
  • General documentation: Update at documentation located in the docs sub-folder. (at least the english portion)

✅ Pull Request Checklist

Before submitting, please ensure:

  • Code compiles with mvn clean verify.
  • Tests pass on JDK 8, 11, 17, 21 (CI will verify).
  • Documentation updated if needed.

📚 Visualize locally the documentation

Install on your computer docsify: npm i docsify-cli -g

And run: docsify serve docs

You can preview the documentation in your browser on http://localhost:3000

🛠️ Adding plugin configuration

This plugin makes it possible to generate multiple OpenAPI documentations from the same codebase. To keep this feature simple, the plugin configuration is mostly split into two parts:

  • The common configuration, defined in CommonApiConfiguration.java
  • The per-document configuration, which extends and overrides the common configuration, and is located in ApiConfiguration.java.

This mechanism is fairly simple for users, but less so for developers of the plugin. Here’s what you need to keep in mind when adding a configuration parameter that is meant to be common:

  1. Add the parameter to CommonApiConfiguration.java, along with its getters and setters.
  2. Add the allocation of this parameter in the constructor with the signature public CommonApiConfiguration(final CommonApiConfiguration commonApiConfiguration).
  3. Add the copy/override behavior for your parameter in the mergeWithCommonApiConfiguration method in the ApiConfiguration.java class. Be sure to add it both where the property is copied from the parent and where its value may potentially be overridden.

📜 License

By contributing, you agree that your contributions will be licensed under the MIT licence