SpringBoot2.x整合Swagger2，远离编写繁重的接

后台开发人员最痛苦的是什么，或许不是写接口，而是写接口文档。接口文档真是体力活，没有什么技术含量，粘贴复制还要心细，能把人累到吐血。呃，写接口文档的那些日子痛不欲生、苦不堪言。希望有那么一天，可以脱离写接口文档的苦海。

这样的一天很快到来了，那就是接触了swagger框架。刚开始，心里满满的兴奋，是不是稍微配置一下，就能摆脱写文档的苦海呢，事实却说，没这么简单，新接触一款工具，第一是要用起来。第二，就是用的好，只有用的好，才能发挥工具的真正价值。

在用的过程中，又发现了一系列问题，这些问题如果不能解决，就发挥不了一个接口文档的作用，还会增加沟通成本，又有哪些问题呢，一一列举下：

1. 基本使用，如何配置，在类、方法、参数上如何加注解，怎样加注解更好？

2. 接口采用了RESTFul风格，路径上的参数和实体中的参数重合了怎么办？

3. 这个接口文档仅仅是接口文档吗？希望能担当测试大任，这样就不用来回切换工具了，真的能如此吗？

4. 2.9.2版本的风格太low怎么办？

SpringBoot2.1.4.RELEASE整合swagger框架，下面一步一步来。

第一步，在pom文件中，引入swagger框架，刚开始使用的是2.2.2版本

<!-- swagger RESTful API 文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>
        <!-- swagger ui  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>   

第二步，添加配置文件

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 在线文档生成,参考网址：https://hacpai.com/article/1534735914420
 * https://blog.csdn.net/sanyaoxu_2/article/details/80555328
 * @author 程就人生
 * @date 2019年5月29日
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("服务接口文档范例")
                .description("服务接口文档，严格遵循RESTful API设计规范。")
                .contact("程就人生")
                .version("1.0")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo)
                .select()
                 //以扫描包的方式
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

}

说明：在配置文件中，已经设置了以扫描包的方式来生成接口文档。
这时启动项目，输入地址localhost:8080/swagger-ui.html，可以看到已经生成的接口文档，界面还是相当漂亮的，这只是加了配置，还未加注解的。

图-1
图-2
图-3
图-4
图-5

第三步，接下来，先了解一下，swagger里面都有哪些注解吧；如果一个注解不加，都是英文的，未免太粗糙，写接口的人能看得懂，对接的未必能看懂，把文档进一步细化一下；

@Api(value=”类的中文说明”, description=”类名称”),类注解，是加在类上的，当然api里面还有其他的参数，暂时没有用到，先忽略，2.9版本只认识tags不认识value

@ApiOperation(value=”方法名称说明”,tags=”方法描述”) 方法上的注解

@ApiImplicitParams({

@ApiImplicitParam(paramType="path", name = "userUid", value = "某个商友信息的uid", required = true, dataType = "String")
}) 方法上需要传递很多参数，可以使用这个进行配置，name必须和方法上的参数保持一致，否则会出现两条

@ApiParam(value=”参数中文名称”，required=true)也可以用这个注解直接在参数的前面增加注解，但是个人更建议使用上一个注解

@ApiIgnore 某个参数需要忽略时，可以使用这个注解

@ApiModel 加在实体类上

@ApiModelProperty(value=”参数中文名称”，required=true)加在实体中的属性上，给属性一个中文描述，让对接人员看得懂；

第四步，实际应用

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.example.demo.entity.User;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

@Api(value="swagger测试", description="TestController")
@RequestMapping("/user")
@RestController
public class TestController {

    @ApiOperation(value="获取用户",notes="根据id获取用户")
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="path", name = "id", value = "用户id", required = true, dataType = "Integer")
    })
    @GetMapping("/{id}")
    public Object get(@PathVariable Integer id){
        User user = new User();
        user.setUsername("程就人生");
        user.setId(id);
        return user;
    }
    
    @ApiOperation(value="新增用户") 
    @PostMapping
    public Object add(User user){
        
        return user;
    }
    
    @ApiOperation(value="修改用户",notes="根据id修改用户")    
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="path", name = "id", value = "用户id", required = true, dataType = "Integer")
    })
    @PutMapping("/{id}")
    public Object update(@PathVariable Integer id, User user){
        
        return user;
    }
    
    @ApiOperation(value="删除用户",notes="根据id删除用户")    
    @ApiImplicitParams({
        @ApiImplicitParam(paramType="path", name = "id", value = "用户id", required = true, dataType = "Integer")
    })
    @DeleteMapping("/{id}")
    public Object delete(@PathVariable Integer id){
        
        return id;
    }   
}

第五步，查看效果，此时，每个方法上都有了说明，方法中的参数也有了说明，有的接口还可以进行测试；

图-6
图-7

但是实体类接收不到参数的呀，而且还不知道实体类中有哪些属性，需要手动输入，这个太太不友好了吧，不能算一个清晰的对接文档，这个有没有办法解决呢？？

听说还有高级第一点的版本，那就试试吧！

第一步，把pom中的引入文件换成2.9.2版本的

<!-- swagger RESTful API 文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger ui  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

第二步，迫不及待的看看效果如何

图-8
图-9
只想说，天哪，界面也太不友好了吧？但是有一点比较好，实体类里面的属性都是可见的，咦，能不能把功能留下，把界面样式换成2.2.2的呢，试一试吧，一试，效果还不错哟！
结果，配置文件就变成了这样的：

<!-- swagger RESTful API 文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger ui  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.2.2</version>
        </dependency>   

效果变成这样的，还是很不错的哟，看一看能不能用来测试，居然可以测试，四个接口都能够测试。

图-10
图-11

总结：

1. 在使用PUT或其他方法的时候，路径上面传递了一个id，/{id}这种的，后面又有实体类的，这时，这个id参数的paramType必须为path，不可以为query，如果写成了query，在接受参数的时候，就会报String转integer的错误，这是因为使用query，把参数拼接在问号后面了，实体里面又有一个，提交给后台的就有两个了，paramType为path在提交后台时，框架默认就会把id封装到实体里面，不会报错了。
2. 方法上的某个参数需要忽略时，可以使用@ApiIgnore进行注解，这样在文档里就不会展示了。
3. 对于实体里面的属性，想添加描述的，可以在属性上增加@ApiModelProperty(value=”参数中文名称”，required=true)，来对参数进行中文描述，还可以添加hidden=true，来设置某个属性不展示。
4. 在2.9.2版本中，@Api不识别value,可以把value改成tags
5. 如果把方法中的notes改成tags，那么每个方法都会单独展示，而不会显示在类的下面。
6. 如果想加个header头，可以在@ApiImplicitParams注解里面，增加一行@ApiImplicitParam(paramType="header", name = "cookie", value = "cookie", required = true, dataType = "String")，设置paramType为header即可。
7. 除了使用@ApiImplicitParam注解方法上的参数，还可以使用@ApiParam(value=”参数中文名称”，required=true)直接加在参数前面。

@ApiOperation(value="修改用户名",notes="根据id修改用户名")
    @PutMapping
    public Object updateUsername(@ApiParam(value="用户id",required=true)@RequestParam Integer id, @ApiParam(value="用户名称",required=true)@RequestParam String username, @ApiIgnore User user){
        
        return user;
    }

图-12
图-13

8. 别用debug模式，否则会很慢很慢；
9. 可能在某些浏览器下，不能正常展示；

10. 不知道屏幕前的您还有什么高见，欢迎点评！

    
    微信扫一扫，关注程就人生