Swagger2 自动生成接口文档

为什么使用

公司服务器程序需要给移动端App等提供数据访问接口，之前接口信息都是使用word文档提供给前端人员使用，后来发现后台稍微修改一下，就需要更改一次文档，有时候修改不及时或者遗漏，容易造成前端和后台接口不一致，因此，后来决定尝试一下使用Swagger2来进行接口文档的描述。事实证明，这样的做法有利于工作效率的提高和前后台人员的沟通。

效果图

本次demo是使用Spring boot来做的，好处是搭建快，使用传统的方式跟这个差不多。

在pom.xml中添加依赖

 <!--  引入swagger包 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>

编写Swagger2的config

新增SwaggerConfig类，进行Swagger2的配置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(getApiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hhm.workswagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo getApiInfo(){
        return new ApiInfoBuilder()
                .title("大标题")
                .description("小标题")
                .version("1.0")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

通过@Configuration和@EnableSwagger2注解就可以使用启用Swagger2的使用了，不过要想显示具体接口的信息，需要在controller中添加注解才能够在Swagger2中展现。

在controller中添加注解

@RestController
@Api(value = "/person", tags = "我的接口模块")
public class PersonController {

    @Autowired
    PersonJpa personJpa;

    private Logger log = LoggerFactory.getLogger(PersonController.class);


    @ApiOperation(value = "查询Person")
    @GetMapping("/query")
    public List<Person> queryUser() {
        List<Person> list = personJpa.findAll();
        log.error("Person信息：" + list.toString());
        return list;
    }
}

一些注解的使用

@Api：用在类上，说明该类的作用

@ApiOperation：用在方法上，说明方法的作用，标注在具体请求上，value和notes的作用差不多，都是对请求进行说明；tags则是对请求进行分类的，比如你有好几个controller，分别属于不同的功能模块，那这里我们就可以使用tags来区分了，看上去很有条理

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

　　paramType：参数放在哪个地方

　　header 请求参数的获取：@RequestHeader

　　query 请求参数的获取：@RequestParam

　　path（用于restful接口） 请求参数的获取：@PathVariable

　　body（不常用）

　　form（不常用）

　　name：参数名

　　dataType：参数类型

　　required：参数是否必须传

　　value：参数的意思

　　defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

　　code：数字，例如400

　　message：信息，例如”请求参数没填好”

　　response：抛出异常的类

@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）表明这是一个被swagger框架管理的model，用于class上
@ApiModel：使用在实体类上，描述实体类。
@ApiModelProperty ：使用在实体类上的成员变量上，描述成员变量的含义。

到这里就可以运行程序进行测试了，访问 http://127.0.0.1:8080/swagger-ui.html 就可以看到上面显示的页面了。

点击try it out!就可以得到进行测试，得到服务器返回的数据。

总结

使用Swagger2在一定程度上可以提高开发效率，后台开发人员不需要去维护接口文档（特别是接口文档多了以后很难及时更新），减少了部分的工作量，可以把更多的精力放在业务逻辑上。但是，使用Swagger2也有不好的地方，因为需要使用好多的注解，会导致controller层的代码阅读起来不是很清晰。（纯粹是个人观点）

demo的地址