Spring Boot+Spring Data Rest：能否用swagger-maven-plugin生成Repository文档？

Yes, absolutely! The reason your Repository docs aren't showing up is that swagger-maven-plugin doesn't automatically detect endpoints generated by Spring Data Rest out of the box—you need to add a few extra configurations to make it work. Here's how to fix this step by step:

1. Add the required dependency #

First, you need to include the Springfox Data Rest module to help Swagger recognize Spring Data Rest endpoints. If you're using Spring Boot 2.x (with Swagger 2), add this to your pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-data-rest</artifactId>
    <version>2.9.2</version>
</dependency>

Note: For Spring Boot 3.x, Swagger 2 is no longer supported—switch to springdoc-openapi instead, and use the springdoc-openapi-data-rest dependency along with the springdoc-maven-plugin.

2. Configure Swagger to scan Spring Data Rest endpoints #

Create a Swagger configuration class and import the SpringDataRestConfiguration to enable support for Spring Data Rest:

@Configuration
@EnableSwagger2
@Import(SpringDataRestConfiguration.class)
public class SwaggerConfig {
    @Bean
    public Docket apiDocumentation() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // Scan your controller, repository, and config packages
                .apis(RequestHandlerSelectors.basePackage("com.yourproject"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(getApiInfo());
    }

    private ApiInfo getApiInfo() {
        return new ApiInfoBuilder()
                .title("Your Project API")
                .description("Full API docs including Spring Data Rest Repository endpoints")
                .version("1.0.0")
                .build();
    }
}

3. Annotate your Repository for better documentation #

Add Swagger annotations to your Repository to make the generated docs more informative:

@RepositoryRestResource(collectionResourceRel = "users", path = "users")
@Api(tags = "User Repository") // Groups endpoints under a tag in Swagger
public interface UserRepository extends JpaRepository<User, Long> {
    @ApiOperation("Find users by their username") // Describes the method
    List<User> findByUsername(@Param("username") @ApiParam("Username to search for") String username);
}

4. Update swagger-maven-plugin configuration #

Make sure your plugin is scanning all relevant packages (including repositories and the Swagger config class) in pom.xml:

<plugin>
    <groupId>com.github.kongchen</groupId>
    <artifactId>swagger-maven-plugin</artifactId>
    <version>3.1.1</version>
    <configuration>
        <apiSources>
            <apiSource>
                <springmvc>true</springmvc>
                <!-- Include your controller, repository, and config packages here -->
                <locations>com.yourproject.controller, com.yourproject.repository, com.yourproject.config</locations>
                <schemes>http,https</schemes>
                <host>localhost:8080</host>
                <basePath>/</basePath>
                <info>
                    <title>Your Project API Docs</title>
                    <version>1.0.0</version>
                    <description>Documentation for both Controller and Spring Data Rest Repository APIs</description>
                </info>
                <swaggerDirectory>${project.build.directory}/swagger</swaggerDirectory>
            </apiSource>
        </apiSources>
    </configuration>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Common Pitfalls to Avoid #

• Version Compatibility: Ensure all Swagger/Springfox dependencies match your Spring Boot version. Mismatched versions often cause silent failures.
• Missing @Import: Forgetting @Import(SpringDataRestConfiguration.class) in your Swagger config means Swagger won't detect Spring Data Rest endpoints.
• Incorrect Package Scanning: If your plugin's <locations> don't include the repository or config packages, those components won't be scanned.

After making these changes, run mvn compile (or the plugin's generate goal directly) and you should see your Repository endpoints included in the generated Swagger documentation!

内容的提问来源于stack exchange，提问作者Gonzalo Santiago