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

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

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

时光机