从零学spring boot-springboot集成swagger

小鱼儿 2024-04-17 06:24 49阅读 0赞

日常开发中，前后端的开发联调都需要定义一个接口文档，定义接口文档是比较耗时的，这边推荐一款插件来根据接口来自动生成接口文档，并且会根据接口的变化而自动更新，解放一部分开发人力。spring boot集成swagger非常简单，只需要以下四步：

### 1. 引入swagger依赖 ###

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

### 2. 编写config类 ###

@EnableSwagger2
    @Configuration
    public class Swagger2Config {
    
        @Value("${swagger.enabled:true}")
        private boolean swaggerEnabled;
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                    // 是否开启
                    .enable(swaggerEnabled).select()
                    // 要扫描的包（包含其子包）
                    .apis(RequestHandlerSelectors.basePackage("com"))
                    .paths(PathSelectors.any()).build().pathMapping("/");
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("网页的title")
                    .description("网站的描述（例如：管理平台dev）")
                    //添加一个联系人，参数分别为姓名，个人网站地址，邮箱
                    .contact(new Contact("name", "url", "email"))
                    .version("1.0.0")
                    .build();
        }
    }

### 3. 在要生成的文档的接口上添加注解 ###

@RestController
    @Api(value = "用于测试", tags = "用于测试的controller")
    public class HelloTest {
    
        @GetMapping("/hello/test")
        @ApiOperation(value = "测试方法", notes = "用于测试的方法")
        public void test(@RequestParam String param){
            System.out.println("hello world");
        }
    }

这里的代码只是举个例子，@Api可以指定对这个类的描述，@ApiOperation则是指定对方法的描述，这些注解可以不写，插件也会生成文档，但是可读性会略差一点，另外，除了这两个注解外，还有其他功能的注解：

@ApiParam(name = “参数名称”, value = “备注说明”, required = 是否必须)：标注在方法的参数上 用于描述参数的名称、备注、是否必须等信息
    @ApiImplicitParams： 用于包含多个@ApiImplicitParam
    @ApiImplicitParam用于描述方法的参数，标注在方法上，和@ApiParam功能一样，只是标注的位置不同而已
    @ApiImplicitParams： 用于包含多个@ApiImplicitParam
    @ApiResponse(code = 0, message = “success”)
    @ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：描述一个model的属性
    @ApiIgnore：用于或略该接口，不生成该接口的文档

当然，常用的还是上面的那两个，有兴趣的可以看一下其它的注解的使用。

### 4. 启动项目，访问文档url ###

启动项目，并访问http://127.0.0.1/swagger-ui.html  
注意：我这边的配置如下：

server.port=80
    server.servlet.context-path=/

访问url根据实际的配置自行修改。访问结果如下：  
![swagger示例][swagger]  
从图中可以看出，我们接口需要哪些参数，是否必填，我们也可以直接在网页上填写参数，并调用接口，查看接口的返回，等于是支持了在线测试接口了。

[swagger]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/16/08d6f3dec4374dc6b2ef0eb04d4bdb0c.png