rest API生成篇：springboot+swagger2路

在项目中，需要对接口进行定义，生成文档，swagger是个不错的选择，使用起来也很方便
这里就来说说它的配置和使用
另外，还有raml-mocker，后期考虑在写一篇吧

第一步：pom.xml修改，引入springboot和swagger:

 <!--spring boot-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <exclusions>
                <exclusion>
                    <!--log4j-slf4j-impl与 logback-classic包不兼容，删除这个包 -->
                    <groupId>ch.qos.logback</groupId>
                    <artifactId>logback-classic</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>
  <!--swagger2-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

第二步：从git上下载一个版本的swagger,地址如下：
https://github.com/swagger-api/swagger-ui/tree/v2.2.10
代码clone下来后，在本地打开，并将dist目录复制到项目中，如下：

image.png

第三步：我们配置下swagger的访问路径，添加swagger.properties,内容如下：

springfox.documentation.swagger.v2.path=/rest/api/doc

同时，修改index.html页面上请求的路径，如下：

image.png

第四步：我们添加SwaggerConfig.java，配置如下：

image.png

图中标注箭头的是主要点，限制范围在apis()中配置

第五步：我们修改WebMvcConfig.java，添加资源路径如下：

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("/rest/api/doc/**").addResourceLocations("classpath:/swagger/dist/");
        super.addResourceHandlers(registry);
    }

做完上述的配置，我们就可以在项目中，进行编码注解了，重点使用如下：
@Api 描述接口对主要用途

@Log4j2
@RestController
@RequestMapping(value="/api/users", produces = MediaType.APPLICATION_JSON_VALUE)
@Api(description = "用户管理")
public class AdminController extends BaseController{

@ApiOperation 描述方法对用处
@ApiImplicitParam 在方法上对参数进行描述，这里是对象，参照dataType
另外还有@ApiImplicitParams

@ApiOperation(value = "保存用户信息",notes = "添加、修改用户基础信息")
    @ApiImplicitParam(name="user",value = "用户对象实体",required = true,dataType = "User")
    @PostMapping(value ="/save")
    public JsonResult create(@RequestBody User user) {

@ApiParam 请求参数属性的描述

  @ApiOperation(value = "删除一个用户",notes = "根据编号删除用户信息")
    @DeleteMapping(value ="/delete/id/{id}")
    public JsonResult delete(@ApiParam(value = "编号",required = true)
            @PathVariable String id) {

实体对象对属性添加描述，可以使用：
@ApiModelProperty，留意hidden，该属性会在输出文档时隐藏

 @ApiModelProperty(hidden=true)
    @Column(name="PICTURE_ID_",nullable = true)
    private String pictureId;

    @ApiModelProperty(value="状态，1正常，0待审核,-1审核失败")
    @Column(name = "STATE_",nullable = true)
    private Integer state;

另外，还可以使用@ApiIgnore: 忽略某类/方法/参数的文档

做好上述配置后，就可以打包运行看效果了
比如，我们先使用maven执行clean package生成一个jar包
执行：java -jar admin.jar
查看log，确认启动成功后，我们打开浏览器访问如下地址：
http://localhost:8080/rest/api/doc/index.html
就可以看到效果了

image.png