按步骤完成一个 spring boot 项目 (四) 配置开发文档 Swagger

按步骤完成一个 spring boot 项目 (四) 配置开发文档
1 每一个项目都需要文档的支持，以往的开发经验觉得业务做到了就可以了，在一个小的团体或者固定团队的开发不需要文档的支持，大家都了解业务需求。以后开发涉及到了微服务架构，项目彼此之间没有太大的沟通，因此如果不能够提供一个有效的文档做支撑，沟通会变得麻烦，会影响项目的开发效率。 同时swagger 提供在线测试工具。可以在浏览器直接测试接口的提交操作。

我们需要增加 maven 依赖。 pom.xml 修改如下：

	<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>

2 项目根目录中增加 config 包 创建 SwaggerConfig.java

package com.ylz.spring_boot.config;
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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.any())
				.paths(PathSelectors.any()).build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().build();
	}
}
     	

重新启动项目： 请求路径为：
http://localhost:8001/swagger-ui.html#/

测试完成

２　我们看到了所有接口都是英文的输入和输出，暂时也不了解接口具体是干什么的．因此我们下一步增加　方法的中文注释　以及　实体　对象　参数的中文配置：

swagger 中关于这些注释都有说明: 我在这里举例说明:

对于controller 类 就是提供接口的类 我们的注释为:

这里注意:

类的注解
@Api(“SysUserController”)

方法的注解:
@ApiOperation(value = “查询所有的用用户信息”, notes = “查询所有的用用户信息”)

参数的注解
@ApiImplicitParams(@ApiImplicitParam(name = “name”, value = “姓名”, paramType = “query”, dataType = “String”))

@Api("SysUserController")                          //增加 swagger api 注释
@RestController
@RequestMapping("/sysuser")
public class SysUserController {

    @Autowired
    private SysUserService sysUserService;

    @ApiOperation(value = "查询所有的用用户信息", notes = "查询所有的用用户信息")
    @ApiImplicitParams(@ApiImplicitParam(name = "name", value = "姓名", paramType = "query", dataType = "String"))
    @GetMapping("")
    public ResponseEntity<List<SysUser>> listSysUser(@RequestParam(required = false) String name) {
        Map results = new HashMap();
        QueryWrapper<SysUser> ew = new QueryWrapper<SysUser>();
        ew.orderByAsc("create_time");
        List<SysUser> postList = sysUserService.list(ew);
        return ResponseEntity.ok(postList);
    }


    @ApiOperation(value = "查询单个用户信息", notes = "查询单个用户信息")
    @ApiImplicitParams(@ApiImplicitParam(name = "id", value = "用户编号", paramType = "query", dataType = "Integer"))
    @GetMapping("/{id}")
    public ResponseEntity<SysUser> getById(@PathVariable("id") String id) {
        SysUser sysuser =new  SysUser();
        QueryWrapper<SysUser> ew = new QueryWrapper<SysUser>();
        ew.eq("id",id);
        if(!"".equals(id)){
            sysuser = sysUserService.getOne(ew);
        }
        return ResponseEntity.ok(sysuser);
    }

效果如图:

实体类注解
@ApiModel(“用户信息表”)

属性注解
@ApiModelProperty(“用户编号”)

@ApiModel("用户信息表")
@Data
@TableName("sys_user")
public class SysUser  implements Serializable {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("用户编号")
    @TableId
    private Long id;

    @ApiModelProperty("用户姓名")
    private String name;

    @ApiModelProperty("用户昵称")
    private String nickName;

    @ApiModelProperty("用户头像")
    private String avatar;

    @ApiModelProperty("用户密码")
    private String password;

效果如下:

异常处理: 报此异常

2020-03-13 08:32:10.384 WARN 1468 — [nio-9088-exec-6] i.s.m.p.AbstractSerializableParameter : Illegal DefaultValue null for parameter type integer

java.lang.NumberFormatException: For input string: “”
at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_101]
at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_101]
at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_101]

修改 xml文件引用即可:

	 <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-annotations</artifactId>
        <version>1.5.21</version>
    </dependency>
    
    <dependency>
        <groupId>io.swagger</groupId>
        <artifactId>swagger-models</artifactId>
        <version>1.5.21</version>
    </dependency>

修改完pom文件,记得重新 maven clean maven compile