Spring Boot 整合 Swagger2

Swagger是一套API文档工具框架，帮助我们摆脱人为的维护API文档

官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

首先添加依赖：

<dependency>
	<groupId>io.springfoxgroupId>
	<artifactId>springfox-swagger2artifactId>
	<version>2.9.2version>
dependency>
<dependency>
	<groupId>io.springfoxgroupId>
	<artifactId>springfox-swagger-uiartifactId>
	<version>2.9.2version>
dependency>

swagger是一套框架，第一个依赖引入Swagger包，第二个依赖是UI包，让界面的风格和可用性得到增强，不然就只会是一个JSON形式的页面。

接下来需要写配置类

以前的版本中（具体是swagger的版本还是spring boot的版本我没有去了解）是在启动类头上添加注解，然后在类中写一个方法继承某个方法（忘记了），不过这个方法已经被建议不要使用，目前大多数的配置还是重新写一个配置类，和启动类同级。

代码如下

//注解标示该类为配置类,@Configuation注解包含了@Component注解
@Configuration
//注解开启 swagger2 功能
@EnableSwagger2
public class Swagger2 {
    /**
     * 构建一个Docket类
     * @return
     */
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SPRING_WEB.SWAGGER_2)
                .apiInfo(apiInfo())//加载api信息
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wmj.blog.controller"))//选择需要监控的包
                .paths(PathSelectors.any())//对所有路径进行监控
                .build();
    }

    /**
     * 构建 api文档的详细信息方法
     * 这里配置的信息都会显示在页面上
     * @return
     */
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("项目Rest Api")//页面标题
                .description("blog后台API文档")//文档描述
                .contact(new Contact("魏MJ","http://118.24.92.222","[email protected]"))//创建人信息
                .version("1.0")//版本
                .build();
    }
}

在配置类中通过注解@EnableSwagger2开启swagger2的功能，也可以在启动类上加这个注解开启swgger2

此时，我们在浏览器中输入抵制就可以访问swagger api文档了，默认的路径是

http://ip:端口/swagger-ui.html

接下来就是写接口了 这里提供一个例子，还是直接上代码

@ResponseBody
    @GetMapping("/login/{phone}/{password}")
    @ApiOperation(
            value = "用户登录",
            notes = "传入手机号和密码，判断是否登陆成功",
            response = User.class
//            tags = {"login"}
    )
    @ApiResponses({
            @ApiResponse(code = 400, message = "Invalid Order") ,
            @ApiResponse(code = 500, message = "server error") ,
            @ApiResponse(code = 200, message = "success")
    })
    public Map<String, Object> Login(
            @PathVariable(value = "phone") String phone,
            @PathVariable(value = "password") String password,
            HttpServletRequest request
    ){
        Map<String, Object> result = userService.getUserByPhone(phone, password);
        if (result.get("User") != null){
            HttpSession session = request.getSession();
            session.setAttribute("UserId",((User) result.get("User")).getId());
            session.setAttribute("UserName",((User) result.get("User")).getUsername());
            session.setAttribute("UserPhone",((User) result.get("User")).getUserphone());
        }
        return result;
    }

从上面的代码我们可以看到很多的注解，基本上都是swagger的注解，这些注解的信息都会在文档中显示

swagger适用于restful风格的接口

这里只是给大家看看怎么写，具体的注解我还需要去整理学习一下，目前我也仅仅是在学习阶段，分享出来和大家一起进步，一起学习。