SpringBoot 集成 Api接口文档生成工具Swagger2

灰太狼 2023-07-24 02:27 37阅读 0赞

**SpringBoot 集成 Api接口文档生成工具Swagger2**

为什么使用Swagger？

随着互联网的发展,微服务逐渐流行起来,在微服务的设计下,微服务必将会有大量的接口,对于清楚的手动编写描述接口文档的话,必定是非常令人头疼抓狂，所以就选择使用Swagger来帮我们实现并解决这个问题。

Swagger的优点：

1.  自动生成文档：只需要一些注解，它就可以根据代码自动生成API文档，保证了文档的时效性。
2.  跨语言性，支持四十多种语言。
3.  Swagger UI呈现出来的是一份可交互的API文档，我们可以直接在文档页面尝试API的调用，简化了准备复杂的调用参数的过程。
4.  还可以将文档规范导入相关的工具，这些工具将会为我们自动地创建自动化测试。

实现：

步骤一：在pom.xml文件中添加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>

步骤二：配置Swagger

@Configuration //该类为配置类
    @EnableSwagger2 //开启Swagger
    public class SwaggerConfig {
    
        @Bean
        public Docket getRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.java.spb"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo(){
            return new ApiInfoBuilder()
                    .title("基于Swagger构建的Rest API 接口文档")
                    .description("使用Swagger构建的Rest API文档既方便又快捷")
                    .contact(new Contact("一个有灵魂的程序员","https://blog.csdn.net/lz527657138","starts@163.com"))//作者信息
                    .version("1.0")
                    .build();
        }
    }

步骤三：Controller类添加Swagger注解

/**
     * 控制层
     */
    @Api(tags = "用户管理")
    @RestController
    public class UserInfoController {
        //注入用户服务层
        @Autowired
        private UserService userService;
    
        /**
         * 获取用户列表
         */
        @GetMapping("/getUsers")
        public List<User> getUsers(Map<String, Object> queryMap){
            List<User> users = userService.getUsers(queryMap);
            return users;
        }
    
        /**
         * 新增用户信息
         */
        @ApiOperation("新增用户信息")
        @PostMapping("/insert")
        public String insertUser(@RequestBody User user){
            Long insert = userService.insert(user);
            return insert>0?"新增成功"+insert:"新增失败" + insert;
        }
    
        /**
         * 根据用户id查询信息
         * 传参形式使用Restful
         */
        @ApiOperation(value = "根据id获取用户详细信息",notes = "使用Restful风格路径传参")
        @GetMapping("/getUser/{id}")
        public User getUserById(@PathVariable("id") Long id){
            User userInfo = userService.getUserById(id);
            return userInfo;
        }
    
        /**
         * 根据id删除用户信息
         */
        @ApiOperation(value = "根据id删除用户信息",notes = "使用Restful风格路径传参")
        @DeleteMapping("/delete/{id}")
        public String deleteById(@PathVariable("id") Long id){
            boolean delete = userService.delete(id);
            return delete==true?"删除成功":"删除失败";
        }
    }

步骤四：实体类添加Swagger注解

@Data
    @NoArgsConstructor //无参构造函数
    @AllArgsConstructor//有参构造(全字段)
    @Accessors(chain = true)//链式; 存取器。通过该注解可以控制getter和setter方法的形式。
    @ApiModel(description = "用户类")
    public class User {
        
        @ApiModelProperty(value = "id")
        private Long id;//主键
       
        @ApiModelProperty(value = "真实姓名",example = "妖怪作妖")
        private String userName;//真实姓名
        
        @ApiModelProperty(value = "登录帐号",example = "lzlz10")
        private String userAccount;//登录帐号
       
        @ApiModelProperty(value = "登录密码",example = "123123123")
        private String userPassword;//登录密码
       
        @ApiModelProperty(value = "创建时间")
        private Date createTime;//创建时间
       
        @ApiModelProperty(value = "修改时间")
        private Date modifyTime;//修改时间
       
        @ApiModelProperty(value = "手机号码",example = "18763372970")
        private String telNum;//手机号码
    
        @ApiModelProperty(value = "性别",example = "0女/1男")
        private Integer gender;//性别;0:女;1:男
    
        @ApiModelProperty(value = "生日",example = "1992-05-21")
        private Date birthday;//生日
    
        @ApiModelProperty(value = "邮箱",example = "example@163.com")
        private String email;//邮箱
    }

步骤五：测试看看效果 http://localhost/swagger-ui.html![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2x6NTI3NjU3MTM4_size_16_color_FFFFFF_t_70][]

如有疑问或问题，请批评指正。

[时光机][Link 1]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2x6NTI3NjU3MTM4_size_16_color_FFFFFF_t_70]: /images/20230528/4759b4b05b4b42f2aa4586cfe9ed4212.png
[Link 1]: https://gitee.com/Azzan/springboot