Skip to content

fixes #267: Generate the readme documentation from the source code #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
guusdk wants to merge 4 commits into
base: main
Choose a base branch
from
Open

fixes #267: Generate the readme documentation from the source code #271

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
31f1de2
fixes #267: Generate readme.html from readme.md during the build
guusdk Sep 25, 2026
dcb529e
Generate the endpoint documentation in the readme from the OpenAPI an…
guusdk Sep 25, 2026
83038c0
Document the data types of the REST API, and generate their documenta…
guusdk Sep 25, 2026
72032dd
Generate readme.html after the generated documentation has been added…
guusdk Sep 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,31 @@ jobs:
secrets:
IGNITE_REALTIME_MAVEN_USERNAME: ${{ secrets.IGNITE_REALTIME_MAVEN_USERNAME }}
IGNITE_REALTIME_MAVEN_PASSWORD: ${{ secrets.IGNITE_REALTIME_MAVEN_PASSWORD }}

readme-up-to-date:
name: Check that the readme documents the current endpoints and data types
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7

- name: Set up Java
uses: actions/setup-java@v4
with:
java-version: 17
distribution: temurin
cache: maven

- name: Regenerate the documentation
run: mvn -B -DskipTests process-classes

- name: Fail when the readme was not up to date
run: |
if ! git diff --exit-code readme.md; then
echo "::error file=readme.md::The documentation of endpoints and data types in readme.md does not match the OpenAPI annotations in the source code. Run 'mvn process-classes' (or any later build phase, like 'mvn package') and commit the updated readme.md."
exit 1
fi

hurl-e2e-test:
name: Hurl E2E Tests
runs-on: ubuntu-latest
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,6 @@ debian/
/AGENTS.md
/CLAUDE.md
/.claude/settings.local.json

# Generated from readme.md during the build
/readme.html
105 changes: 105 additions & 0 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,111 @@
<artifactId>maven-surefire-plugin</artifactId>
<version>3.6.0</version> <!-- Override inherited 2.17 to enable JUnit 5 tests -->
</plugin>

<!-- Generate the documentation of endpoints and data types in readme.md from the OpenAPI annotations, so that it can't get out of sync with the implementation. -->
<plugin>
<!-- Generate the OpenAPI specification from the annotations in the compiled classes. -->
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-maven-plugin</artifactId>
<version>${swagger.version}</version>
<executions>
<execution>
<id>generate-openapi-spec</id>
<phase>process-classes</phase>
<goals>
<goal>resolve</goal>
</goals>
</execution>
</executions>
<configuration>
<outputPath>${project.build.directory}/openapi</outputPath>
<outputFileName>openapi</outputFileName>
<outputFormat>JSON</outputFormat>
<prettyPrint>true</prettyPrint>
<resourcePackages>
<package>org.jivesoftware.openfire.plugin.rest.service</package>
</resourcePackages>
</configuration>
</plugin>
<plugin>
<!-- Replace the documentation of endpoints and data types in readme.md with documentation generated from the OpenAPI specification. -->
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.6.4</version>
<executions>
<execution>
<id>generate-readme-documentation</id>
<phase>process-classes</phase>
<goals>
<goal>exec</goal>
</goals>
<configuration>
<executable>${java.home}/bin/java</executable>
<!-- 'compile' includes the 'provided' dependencies (like Openfire), which provide the JAXB implementation that the generator uses. -->
<classpathScope>compile</classpathScope>
<arguments>
<argument>-Dslf4j.internal.verbosity=ERROR</argument>
<argument>-classpath</argument>
<classpath/>
<argument>${project.basedir}/src/build/ReadmeGenerator.java</argument>
<argument>${project.build.directory}/openapi/openapi.json</argument>
<argument>${project.basedir}/readme.md</argument>
</arguments>
</configuration>
</execution>
</executions>
</plugin>

<!-- Generate readme.html from readme.md, so that the two can't get out of sync. This is done in the 'prepare-package'
phase, after readme.md has been updated with the generated documentation (in the 'process-classes' phase). -->
<plugin>
<!-- Isolate readme.md, to prevent other (untracked) markdown files in the project root from being rendered and packaged. -->
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-readme-markdown</id>
<phase>prepare-package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/readme</outputDirectory>
<resources>
<resource>
<directory>${project.basedir}</directory>
<includes>
<include>readme.md</include>
</includes>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<!-- The output is written to the project root, as that's where the plugin assembly picks up readme.html. -->
<groupId>com.ruleoftech</groupId>
<artifactId>markdown-page-generator-plugin</artifactId>
<version>2.5.2</version>
<executions>
<execution>
<id>generate-readme-html</id>
<phase>prepare-package</phase>
<goals>
<goal>generate</goal>
</goals>
</execution>
</executions>
<configuration>
<inputDirectory>${project.build.directory}/readme</inputDirectory>
<outputDirectory>${project.basedir}</outputDirectory>
<headerHtmlFile>${project.basedir}/src/readme/header.html</headerHtmlFile>
<footerHtmlFile>${project.basedir}/src/readme/footer.html</footerHtmlFile>
<defaultTitle>Openfire REST API Plugin Readme</defaultTitle>
<alwaysUseDefaultTitle>true</alwaysUseDefaultTitle>
<pegdownExtensions>TABLES,FENCED_CODE_BLOCKS,AUTOLINKS,STRIKETHROUGH,ANCHORLINKS</pegdownExtensions>
</configuration>
</plugin>
</plugins>
</build>

Expand Down
Loading
Loading