使用Swagger生成开发文档和前端交互

1.Swagger是什么？

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

个人觉得，swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中，发生过多次：修改代码但是没有更新文档，前端还是按照老旧的文档进行开发，在联调过程中才发现问题的情况（当然依据开闭原则，对接口的修改是不允许的，但是在项目不稳定阶段，这种情况很难避免）。

2.Spring Boot集成Swagger2

一、引入依赖：

http://mvnrepository.com中搜索springFox，引入Swagger2和Swagger Ui的依赖：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger2</artifactId>            <version>2.7.0</version>        </dependency>        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->        <dependency>            <groupId>io.springfox</groupId>            <artifactId>springfox-swagger-ui</artifactId>            <version>2.7.0</version>        </dependency>

二、启动类DemoApplication加入@EnableSwagger2注解

@SpringBootApplication@RestController@EnableSwagger2public class DemoApplication {    public static void main(String[] args) {        SpringApplication.run(DemoApplication.class, args);    }    @GetMapping("/hello")    public String hello(){        return "hello spring security";    }}

三、注入资源配置文件（UI视图的配置）

@Configuration@EnableSwagger2public class WebConfig extends WebMvcConfigurerAdapter{    /**     * 这个地方要重新注入一下资源文件，不然不会注入资源的，也没有注入requestHandlerMappping,相当于xml配置的     *  <!--swagger资源配置-->     *  <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>     *  <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>     *  不知道为什么，这也是spring boot的一个缺点（菜鸟觉得的）     * @param registry     */    @Override    public void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("swagger-ui.html")                .addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars*")                .addResourceLocations("classpath:/META-INF/resources/webjars/");    }}

四、启动服务，访问 localhost:8080/swagger-ui.html 即可看到服务的api文档

五、可加入@ApiModelProperty注解更方便前端开发人员理解传入参数为对象的属性（注解加在实体类的属性中）

public class UserQueryCondition {    private String username;    @ApiModelProperty(value = "用户年龄起始值")    private int age;    @ApiModelProperty(value = "用户年龄终止值")    private int ageTo;    private String xxx;    public String getUsername() {        return username;    }    public void setUsername(String username) {        this.username = username;    }    public int getAge() {        return age;    }    public void setAge(int age) {        this.age = age;    }    public int getAgeTo() {        return ageTo;    }    public void setAgeTo(int ageTo) {        this.ageTo = ageTo;    }    public String getXxx() {        return xxx;    }    public void setXxx(String xxx) {        this.xxx = xxx;    }}

六、可加入@ApiOperation注解让前端开发人员理解发送http请求对应的Controller方法的功能（注解加在Controller方法上）

    @GetMapping    @JsonView(User.UserSimpleView.class)    @ApiOperation(value = "用户查询服务")    public List<User> query(UserQueryCondition condition,@PageableDefault(page=2,size=17,sort="username,asc") Pageable pageable){//用spring自带的pageable对象来得到分页信息        System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.MULTI_LINE_STYLE));        System.out.println(pageable.getPageSize());        System.out.println(pageable.getPageNumber());        System.out.println(pageable.getSort());        List<User> users = new ArrayList<>();        users.add(new User());        users.add(new User());        users.add(new User());        return users;    }

七、可加入@ApiParam注解让前端开发人员理解传入的一般请求参数（如String类型）的功能（注解加在Controller方法的传入参数上）

    @GetMapping("/{id:\\d+}")    @JsonView(User.UserDetailView.class)    public User getInfo(@ApiParam("用户id") @PathVariable String id){        //throw new UserNotExistException(id);        System.out.println("进入getInfo服务");        User user = new User();        user.setUsername("tom");        return user;    }

八、查看文档注解的效果