SpringBoot配置swagger2过程和详解

Love The Way You Lie 2023-02-21 06:45 16阅读 0赞

### **pom文件** ###

首先pom文件中引入依赖

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

### **配置文件** ###

enable作为swagger开关放在配置文件中，可以通过更改配置文件来控制Swagger-ui的显示和隐藏

#swagger开关
    swagger2.enable=true

### **SwaggerConfig** ###

config包下创建SwaggerConfig类

@Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        //读取配置文件中的enable，true为显示，false为隐藏
        @Value("${swagger2.enable}")
        private boolean enable;
    
        @Bean
        public Docket createDocke(){
            return new Docket(DocumentationType.SWAGGER_2)
                    //进入swagger-ui的信息
                    .apiInfo(apiInfo())
                    .select()
                    //暴露所有controller类的所在的包路径
                    .apis(RequestHandlerSelectors.basePackage("com.liang.web.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    .enable(enable);
        }
        //进入swagger-ui的信息
        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    //该项目的名字
                    .title("Spring Boot 2.x教程")
                    //该项目的描述
                    .description("spring boot2.x 描述")
                    .version("1.0")
                    .build();
        }
    }

此时运行项目便可以进入到Swagger页面

在网页中输入"本机地址:端口号/swagger-ui.html"

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ_size_16_color_FFFFFF_t_70][]

## ##

### **经常用的Swagger注解** ###

实体Model中注解

@Data
    //实体路径和描述
    @ApiModel(value = "com.liang.web.Model.UpdateUserModel",description = "接收更新用户数据")
    public class UpdateUserModel {
        //字段描述
        @ApiModelProperty(value = "用户id")
        private String id;
        @ApiModelProperty(value = "账号")
        private String username;
        @ApiModelProperty(value = "密码")
        private String password;
        @ApiModelProperty(value = "性别")
        private String sex;
        @ApiModelProperty(value = "手机号")
        private String phone;
        @ApiModelProperty(value = "地区")
        private String createWhere;
        @ApiModelProperty(value = "邮件")
        private String email;
        @ApiModelProperty(value = "昵称")
        private String nickName;
    }

controller层注解

@RestController()
    @RequestMapping("/api")
    //接口模块描述信息
    @Api(tags = "用户模块",description = "用户相关模块接口")
    public class UserController {
        @Autowired
        private UserService userService;
    
        @GetMapping("/getUser")
        //接口描述信息
        @ApiOperation(value = "获取用户详情")
        @ApiImplicitParams({
                //给Swagger-UI中的输入框中设置默认值
                @ApiImplicitParam(name = "id",value = "用户id",defaultValue = "123456")
        })
        public SysUser getUserDetail(@ApiParam(value = "用户id",required = true) @RequestParam String id) {
            return userService.getUserInfo(id);
        }
    
        @PutMapping("/user")
        //接口描述信息
        @ApiOperation(value = "获取用户详情")
        public String updateUserInfo(@RequestBody UpdateUserModel userModel) {
            return userService.updateUserInfo(userModel);
        } 
    }

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ_size_16_color_FFFFFF_t_70 1][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ_size_16_color_FFFFFF_t_70 2][]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200629162036293.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200629164111925.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200629164304711.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2xpYW5namlhYmFvNTU1NQ==,size_16,color_FFFFFF,t_70