If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/springfox/springfox shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 9 active contributors
• Apache-2.0 licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 82% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live springfox/springfox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/springfox/springfox.

What it runs against: a local clone of springfox/springfox — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in springfox/springfox | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 811 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of springfox/springfox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/springfox/springfox.git
#   cd springfox
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of springfox/springfox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "springfox/springfox(\\.git)?\\b" \\
  && ok "origin remote is springfox/springfox" \\
  || miss "origin remote is not springfox/springfox (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f "gradle/dependencies.gradle" \\
  && ok "gradle/dependencies.gradle" \\
  || miss "missing critical file: gradle/dependencies.gradle"
test -f "buildSrc/src/main/groovy/springfox/gradlebuild/plugins/MultiProjectReleasePlugin.groovy" \\
  && ok "buildSrc/src/main/groovy/springfox/gradlebuild/plugins/MultiProjectReleasePlugin.groovy" \\
  || miss "missing critical file: buildSrc/src/main/groovy/springfox/gradlebuild/plugins/MultiProjectReleasePlugin.groovy"
test -f "oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiApplication.java" \\
  && ok "oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiApplication.java" \\
  || miss "missing critical file: oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiApplication.java"
test -f "oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java" \\
  && ok "oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java" \\
  || miss "missing critical file: oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 811 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~781d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/springfox/springfox"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Springfox is an automated JSON API documentation generator for Spring-based REST APIs that produces Swagger/OpenAPI specifications. It introspects Spring controller annotations at runtime and generates machine-readable API contracts (swagger.json) without requiring manual YAML/JSON maintenance, enabling interactive API exploration via Swagger UI and automatic client code generation. Multi-module Gradle monorepo with custom build infrastructure in buildSrc/ (containing versioning, release, and CI automation). Core modules likely under separate directories (not fully listed) that handle Swagger spec generation, Spring integration, and UI serving. buildSrc/src/main/groovy/springfox/gradlebuild contains plugin infrastructure (MultiProjectReleasePlugin, version strategies), and .circleci/config.yml defines CI orchestration.

Spring framework backend engineers building REST APIs who need to automatically document their endpoints for frontend developers, API consumers, and tooling. DevOps teams integrating API documentation into CI/CD pipelines and API gateway systems also rely on it for contract-first development.

Production-ready and actively maintained. The project has extensive CI/CD (CircleCI, Codecov, SonarCloud), comprehensive test coverage (491K Java LOC with Groovy/Spock tests), semantic versioning in buildSrc, and clear contribution guidelines. Recent activity visible through CircleCI builds and multi-release plugin infrastructure indicates ongoing development.

Moderate risk: the codebase spans two major Swagger/OpenAPI spec versions (2.0 and 3.0), creating potential compatibility issues. Dependency on Spring's annotation processing makes it sensitive to Spring Framework API changes. The buildSrc custom release tooling (BumpAndTagTask, GitDescribeVersioningStrategy) adds maintenance overhead. No visible recent commit timestamp provided, so activity level is unclear.

Build infrastructure is actively being maintained—the codebase includes semantic versioning (SemanticVersion, GitDescribeVersioningStrategy), CI/CD integration, and stale issue automation (.github/stale.yml). The presence of CONTRIBUTING.md, PULL_REQUEST_TEMPLATE.md, and Bintray/Artifactory publishing setup suggests an actively managed release cycle, though specific recent feature work is not visible in the file structure provided.

git clone https://github.com/springfox/springfox.git && cd springfox && ./gradlew build

Daily commands: After cloning, run ./gradlew build to compile and run tests. For development IDE setup, Gradle applies the 'idea' plugin (see build.gradle), so run ./gradlew idea to generate IntelliJ project files. The asciidoctor plugin (org.asciidoctor.jvm.convert) suggests running ./gradlew asciidoctor to build documentation locally.

• build.gradle — Root Gradle build configuration defining all plugins, dependencies, and multi-project release strategy; essential for understanding the build system and dependency management across the entire codebase.
• gradle/dependencies.gradle — Centralized dependency declarations for Spring, Swagger/OpenAPI, and testing frameworks; all contributors must understand version constraints and transitive dependencies.
• buildSrc/src/main/groovy/springfox/gradlebuild/plugins/MultiProjectReleasePlugin.groovy — Core Gradle plugin orchestrating multi-module builds and release workflows; critical for anyone modifying build infrastructure or release processes.
• oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiApplication.java — Primary test application demonstrating Springfox integration with Spring Boot and OpenAPI; entry point for understanding how the library is configured and used.
• oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java — Configuration class showing Springfox bean setup and customization patterns; essential reference for extending or configuring the documentation generation.
• .circleci/config.yml — CI/CD pipeline defining test execution, SonarQube analysis, and Bintray publishing; critical for understanding quality gates and release automation.
• README.md — Project overview, badges, and high-level documentation; the entry point for understanding Springfox's purpose as automated JSON API documentation for Spring.

Add a new REST API endpoint

1. Create a new Spring @RestController class in oas-contract-tests/src/main/java/springfox/test/contract/oas/api/ with @RequestMapping and @GetMapping/@PostMapping/@PutMapping annotations. (oas-contract-tests/src/main/java/springfox/test/contract/oas/api/PetApiController.java)
2. Annotate controller methods with @Operation, @ApiResponse, @Parameter to provide OpenAPI documentation details. (oas-contract-tests/src/main/java/springfox/test/contract/oas/api/PetApiController.java)
3. Verify the endpoint is automatically documented by checking the generated /v3/api-docs JSON response. (oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiApplication.java)

Customize Springfox OpenAPI documentation generation

1. Create or modify the OpenApiTestConfig class to define a @Bean Docket configuration with custom title, description, and contact information. (oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java)
2. Use groupName() and select() to filter which endpoints are included in the OpenAPI spec (e.g., only v2 API paths). (oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java)
3. Apply security schemes via securitySchemes() method to document authentication requirements (OAuth2, API Key, etc.). (oas-contract-tests/src/main/java/springfox/test/contract/oas/SecuritySupport.java)

Configure security for API documentation

1. Create a SecuritySupport class with static methods returning SecurityScheme objects (ApiKey, OAuth2, OpenIdConnect, HttpBearer). (oas-contract-tests/src/main/java/springfox/test/contract/oas/SecuritySupport.java)
2. Register security schemes in the Docket configuration by calling securitySchemes() and securityContexts() to map schemes to endpoints. (oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiTestConfig.java)
3. Verify security definitions appear in the /v3/api-docs response under components.securitySchemes. (oas-contract-tests/src/main/java/springfox/test/contract/oas/OpenApiApplication.java)

Release a new version of Springfox

1. Update version in .version file or use git tags; the GitDescribeVersioningStrategy will automatically detect and use semantic versioning. (.version)
2. Ensure all tests pass locally and CircleCI pipeline completes the test job by reviewing .circleci/config.yml workflow stages. (.circleci/config.yml)
3. Trigger the MultiProjectReleasePlugin release task which bumps version, tags the repository, and publishes artifacts to Bintray via gradle/publishing.gradle configuration. (buildSrc/src/main/groovy/springfox/gradlebuild/plugins/MultiProjectReleasePlugin.groovy)

• Spring Framework & Spring Boot — Springfox is built specifically to auto-generate OpenAPI/Swagger docs for Spring-based REST APIs; tight integration with Spring annotations (@RestController, @GetMapping, etc.) enables zero-configuration documentation.
• Gradle with multi-module build — Manages complex multi-module project structure with custom plugins for semantic versioning, release automation, and CI/CD integration; supports independent module versioning and publishing.
• OpenAPI 3.0 / Swagger specification — Springfox generates machine-readable API contracts in OpenAPI format; enables client code generation, interactive API documentation (Swagger UI), and API gateway integration.
• CircleCI for CI/CD — Automates test execution, SonarQube code quality analysis, code coverage reporting, and artifact publishing to Bintray; enforces quality gates before release.
• Groovy for build scripting — buildSrc gradle plugins written in Groovy for DSL expressiveness; enables custom version strategies, release tasks, and multi-project orchestration without external tooling.

• Auto-generation of API documentation from annotations instead of manual specs
  • Why: Reduces documentation drift and maintenance burden; single source of truth in
  • Consequence: undefined

1. The buildSrc custom release tooling (CheckRequiredSecretsTask, BintrayCredentials, GitTaggingSupport) requires Bintray/Artifactory credentials in environment or gradle.properties for release builds—missing credentials will fail artifact publishing. 2. JVM argument -Dorg.spockframework.mock.ignoreByteBuddy=true in test block (build.gradle) is required for Spock mocking to work correctly; local test runs missing this flag may encounter ByteBuddy conflicts. 3. The .java-version file suggests a specific JDK version is pinned; using a different JDK may cause compilation failures due to @parameters flag in compiler options. 4. CircleCI config is linked but actual workflow/job definitions are not shown—builds may depend on environment variables or secrets configured in CircleCI UI rather than in the repo.

• Annotation Introspection — Springfox's core capability: it reads Spring's @RequestMapping, @PathVariable, @RequestParam at runtime to auto-generate API contracts without manual specification
• Swagger/OpenAPI Specification — Springfox generates compliant swagger.json (2.0) or openapi.json (3.0) documents; understanding the spec structure is essential for troubleshooting contract issues and version compatibility
• Semantic Versioning & Git-based Release Automation — buildSrc implements custom SemanticVersion and GitDescribeVersioningStrategy; contributors must understand how version bumps are computed from git tags to avoid manual version conflicts
• Gradle Plugin Development — buildSrc/springfox/gradlebuild/ implements MultiProjectReleasePlugin and custom tasks; understanding Gradle plugin architecture is necessary for modifying release logic or adding new build phases
• Spock Testing Framework — The codebase uses Groovy/Spock specs instead of JUnit; new contributors must learn Spock's BDD syntax (given/when/then) and Mock/Stub semantics to write and debug tests
• Code Coverage via JaCoCo — All subprojects apply jacoco plugin and generate XML/HTML coverage reports; CI gates on SonarQube coverage thresholds, so understanding JaCoCo exclusions and report interpretation is necessary
• Multi-Module Build Orchestration — Springfox is a monorepo with dozens of modules coordinated by root build.gradle and custom release tasks; understanding subproject dependency graphs and version consistency is critical for adding new modules

• springfox/springfox-demos — Official examples repository demonstrating Springfox integration patterns with various Spring Boot configurations and custom Swagger setups
• swagger-api/swagger-ui — The underlying Swagger UI library that Springfox wraps and serves; understanding its configuration options is essential for customizing API documentation UI
• OAI/OpenAPI-Specification — OpenAPI/Swagger specification standard that Springfox generates; reference for understanding contract format and versioning (2.0 vs 3.0 differences)
• springdoc/springdoc-openapi — Modern alternative to Springfox using Spring Boot's native OpenAPI support; evaluating tradeoffs between the two is relevant for new Spring projects
• spring-projects/spring-framework — Core dependency providing @RequestMapping, @RestController, and annotation introspection capabilities that Springfox relies on for API metadata extraction

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for buildSrc custom Gradle tasks

The buildSrc directory contains custom Gradle plugins and tasks (BumpAndTagTask, CheckCleanWorkspaceTask, CheckGitBranchTask, etc.) for the multi-project release process, but buildSrc/src/test only has version-related tests. There are no tests for the release workflow tasks themselves. Adding integration tests would prevent regressions in the release pipeline and help new contributors understand the release process.

• [ ] Create buildSrc/src/test/groovy/springfox/gradlebuild/tasks/ directory
• [ ] Add unit tests for BumpAndTagTask.groovy covering git tag creation scenarios
• [ ] Add unit tests for CheckCleanWorkspaceTask.groovy covering dirty/clean workspace detection
• [ ] Add unit tests for CheckGitBranchTask.groovy covering branch validation logic
• [ ] Add unit tests for ReleaseTask.groovy covering the orchestration of sub-tasks

Add GitHub Actions CI workflow for Java/Gradle builds

The project uses CircleCI (via .circleci/config.yml) but lacks a GitHub Actions workflow file. GitHub Actions would provide faster feedback directly in PRs, reduce external dependency on CircleCI, and is the modern GitHub-native standard. This enables contributors to validate builds locally and see results faster.

• [ ] Create .github/workflows/build.yml with matrix strategy for Java 8, 11, 14+
• [ ] Configure gradle build task with caching for faster builds
• [ ] Add test reporting and code coverage upload to Codecov
• [ ] Configure workflow to run on push to master and all pull requests
• [ ] Add checkstyle validation step referencing config/checkstyle.xml

Document Gradle extension points and plugin architecture in buildSrc/README.md

buildSrc/README.md exists but is minimal. The custom Gradle plugin system (springfox-multi-release plugin, version strategies, git support) is powerful but undocumented. New contributors working on build logic cannot easily understand how to extend or modify the build system without reverse-engineering the code.

• [ ] Expand buildSrc/README.md with overview of custom plugins (springfox-multi-release, versioning strategies)
• [ ] Document the VersioningStrategy interface and existing implementations (FileVersionStrategy, GitDescribeVersioningStrategy)
• [ ] Add section on GitVersionParser parsing logic with examples of git describe output
• [ ] Document the ReleaseTask workflow and dependencies between pre-release tasks (CheckCleanWorkspaceTask, CheckGitBranchTask, etc.)
• [ ] Add code examples showing how to extend SemanticVersion and add custom versioning logic

• Add missing unit tests for buildSrc Gradle tasks: CheckCleanWorkspaceTask.groovy, CheckGitBranchTask.groovy, and IntermediaryTask.groovy lack test coverage visible in buildSrc/src/test/. Write Spock specs in buildSrc/src/test/groovy/springfox/gradlebuild/ to test task execution and git operations.
• Expand Checkstyle coverage documentation: config/checkstyle.xml enforces style rules but .github/CONTRIBUTING.md does not list specific style violations to watch for. Document 5-10 common style violations (naming, line length, import order) with examples in CONTRIBUTING.md to help new contributors avoid CI failures.
• Add a getting-started example integration test: The repo references examples/ in README but that directory is not in the file list. Create a minimal springfox example module demonstrating @RestController instrumentation, custom Swagger configuration, and Swagger UI setup with integration tests validating the generated swagger.json schema.

The Springfox codebase has moderate security concerns primarily related to outdated dependencies and build infrastructure. Critical issues include the use of deprecated JCenter repository and outdated Gradle plugins with known vulnerabilities. The lack of dependency verification and integrity checks increases supply chain attack risk. While the project structure appears well-organized, explicit security configurations are not visible. Immediate actions needed: migrate from jcenter to Maven Central, update all Gradle plugins, implement dependency locking and verification, and ensure credentials are never stored in version control. The project would benefit from implementing a formal security policy and regular dependency scanning.

• High · Outdated Gradle Plugins with Known Vulnerabilities — build.gradle - plugin declarations. The build.gradle file specifies multiple Gradle plugins with outdated versions that may contain known security vulnerabilities. Specifically: com.jfrog.bintray (1.8.5), com.jfrog.artifactory (4.16.1), and com.github.kt3k.coveralls (2.10.1) are several years old and likely have unpatched security issues. Fix: Update all Gradle plugins to their latest stable versions. Establish a regular dependency update schedule and use dependency vulnerability scanning tools like OWASP Dependency-Check or Snyk.
• High · Insecure JCenter Repository — build.gradle - allprojects repositories section. The codebase uses 'jcenter()' repository which was sunset by JFrog in 2021. This creates risks as the repository is no longer maintained and could serve compromised dependencies. Additionally, using a single repository without fallback increases supply chain risk. Fix: Replace jcenter() with Maven Central (mavenCentral()) and add additional secure repositories like Google's Maven Repository. Implement repository authentication and verification.
• Medium · Missing Dependency Integrity Verification — build.gradle and gradle configuration files. No evidence of dependency signature verification, checksums, or lock files (gradle.lock). This makes the build susceptible to dependency substitution attacks or compromised artifact downloads. Fix: Enable Gradle dependency verification by creating a gradle/verification-metadata.xml file. Use gradle.lockfile for reproducible builds and consider using dependency locking via './gradlew dependencies --write-locks'.
• Medium · Potential Credentials Exposure in Build Files — buildSrc/src/main/groovy/springfox/gradlebuild/BintrayCredentials.groovy. The buildSrc directory contains BintrayCredentials.groovy which likely handles credentials. While not directly visible in the provided snippet, build scripts that handle credentials should never store them in version control or use hardcoded values. Fix: Ensure credentials are only loaded from environment variables or secure credential stores (e.g., CI/CD secrets, HashiCorp Vault). Never commit credentials to the repository. Scan git history for accidentally committed secrets using tools like git-secrets or TruffleHog.
• Medium · No Security Headers or OWASP Configuration Visible — Project-wide - no visible security configuration. As an API documentation framework, Springfox should implement security best practices. No evidence of security header configuration, CORS policies, or OWASP protections in the visible codebase structure. Fix: Implement Spring Security configuration with appropriate headers (X-Content-Type-Options, X-Frame-Options, Content-Security-Policy). Configure CORS policies restrictively and validate all inputs to prevent XSS and injection attacks.
• Medium · Outdated Gradle Wrapper Version — gradle/wrapper/gradle-wrapper.properties and gradle/wrapper/gradle-wrapper.jar. While not explicitly shown, Gradle wrapper files should be regularly updated to use recent Gradle versions that include security patches and improvements. Fix: Update Gradle wrapper to the latest stable version using './gradlew wrapper --gradle-version=latest'. Validate wrapper checksums and document the update process.
• Low · Missing SECURITY.md File — .github/ directory. No visible SECURITY.md or security policy file in the .github directory to guide users on responsible disclosure of security vulnerabilities. Fix: Create a .github/SECURITY.md file outlining the security vulnerability reporting process and expected response times, following GitHub's recommended format.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.