Spring Boot中使用Swagger2快速构建RESTful API文档

蔚落 2022-02-20 20:43 241阅读 0赞

Swagger2，它可以轻松的整合到Spring Boot中，并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FiY18xMjM0NTZfX18_size_16_color_FFFFFF_t_70][]

在`pom.xml`中加入Swagger2的依赖

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.2.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.2.2</version>
    </dependency>

## 创建Swagger2配置类 ##

在`Application.java`同级创建Swagger2的配置类`Swagger2`。注意basepackage中的包名要改为你自己的包名，才可以扫描的到

@Configuration
    @EnableSwagger2
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.lyb.demo.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("更多Spring Boot相关文章请关注：linyongbin")
                    .contact("linyongbin")
                    .version("1.0")
                    .build();
        }
    
    }

我们通过`@ApiOperation`注解来给API增加说明、通过`@ApiImplicitParams`、`@ApiImplicitParam`注解来给参数增加说明。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FiY18xMjM0NTZfX18_size_16_color_FFFFFF_t_70 1][]

启动Spring Boot程序，访问：[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]  
就能看到前文所展示的RESTful API的页面，我们还可以在上面对我们的接口进行测试

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FiY18xMjM0NTZfX18_size_16_color_FFFFFF_t_70]: /images/20220221/5f20d033878e45899a9dffafeb2a950b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2FiY18xMjM0NTZfX18_size_16_color_FFFFFF_t_70 1]: /images/20220221/26c44bee5b3e4b5bb8f411651c47274f.png
[http_localhost_8080_swagger-ui.html]: https://link.jianshu.com/?t=http://localhost:8080/swagger-ui.html