spring boot 开发数据接口 spring boot api接口

导读

当你在使用springboot开发微服务的时候，你是如何把定义的接口信息告诉给调用方的呢？如：接口地址，接口参数，参数类型，参数说明，返回响应对象等信息说明，或许你可以用word文档来编辑接口信息，然后转给调用方，或者第三方api管理工具，但是这些都给你的工作增加了额外的负担，因此，我们要使用springboot整合swagger2来实现这个api接口文档编辑管理。

新建springboot-swagger2项目

依赖包如下：

org.springframework.boot        spring-boot-starter-parent        2.2.6.RELEASEorg.springframework.boot        spring-boot-starter-web        org.projectlombok        lombok        io.springfox        springfox-swagger2        2.9.2io.springfox        springfox-swagger-ui        2.9.2

新建SwaggerConfig类

@Configuration@EnableSwagger2//启动swaggerpublic class SwaggerConfig {        @Bean        public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)            .apiInfo(apiInfo())            .select()            .apis(RequestHandlerSelectors.basePackage("com.panshi.it"))//指定扫描controller包            .paths(PathSelectors.any())            .build();        }        /**        * 定义Api信息        * @return        */        private ApiInfo apiInfo() {              return new ApiInfoBuilder()              .title("用户API")//接口标题              .description("新增用户，查询用户")//接口具体描述              .termsOfServiceUrl("http://127.0.0.1:8080/")//调用服务地址              .contact(new Contact("我们","http://test.com","[e-mail]"))//联系我们信息              .version("version 1.0")//定义版本号              .build();        }}

新建用户API-UserController类

@Controller@Slf4jpublic class UserController {        /**        * 新增用户对象        */        @GetMapping("addUser")        @ResponseBody        public ResponseVO addUser(UserVO userVO){        log.info("新增用户对象={}",userVO);        return ResponseVO.success();        }}

UserVO类

@Datapublic class UserVO {    String userName;    String password;    Integer age;}

ResponseVO类

/*** 统一响应VO*/@Data@AllArgsConstructor@NoArgsConstructorpublic class ResponseVO {        /**        * 状态码        */        String code;        /**        * 状态信息        */        String msg;        /**        * 返回数据对象        */        T data;        /**        * 定义一个静态方法，返回成功状态码        * @return 响应对象        */        public static ResponseVO success(){        return success(null);        }        /**        * 定义一个静态方法，返回成功        * @param data 设置成功返回参数        * @return        */        public static  ResponseVO success(T data){        return new ResponseVO("200","操作成功",data);        }        /**        * 定义一个静态方法，返回失败状态码，以及指定失败信息        * @param msg 失败信息        * @return 响应对象        */        public static ResponseVO fail(String msg){        return new ResponseVO("999",msg,null);        }}

编写启动SpringBootSwaggerApp类

@SpringBootApplicationpublic class SpringBootSwaggerApp {  public static void main(String[] args) {  SpringApplication.run(SpringBootSwaggerApp.class,args);  }}

访问api接口文档

启动服务后，该项目就可以自动生成api接口文档信息了，访问接口文档地址：

http://localhost:8080/swagger-ui.html

localhost:8080 就是该项目服务地址以及端口swagger-ui.html 是固定文件名称，系统自动生成。

接口页面说明

总接口文档说明

具体接口

user-controller就是一个接口，点击">"展开，看到如下，model对象都是随着响应对象而改变,不是固定的。

接口描述说明

models就是所有接口响应model对象，点击">"展开，看到如下：

models说明

点击 “Try it out” 按钮进行接口文档测试，效果如下

输入接口参数

响应结果

目前我们已经把swagger项目使用起来了，使用起来非常简单，但是现在目前远远还不够，我们继续把接口参数丰富起来。

编辑UserController类

(1)在UserController类上加上注解：@Api(tags = "用户接口")，以上就是定义了一个名称

@Api(tags = "用户接口")@Controller@Slf4jpublic class UserController

(2)在addUser方法：@ApiOperation("新增用户信息接口")，对该方法定义了一个接口说明

@ApiOperation(value = "新增用户信息接口",notes = "新增用户信息接口，新增用户，校验用户是否存在")

@GetMapping("addUser")@ResponseBodypublic ResponseVO addUser(UserVO userVO)

(3)新增一个查询方法,使用@ApiImplicitParam(name = "age", value = "用户年龄", required = true)注解，代码该参数是必填

@ApiOperation("根据用户年龄查询用户信息")@ApiImplicitParam(name = "age", value = "用户年龄", required = true)@GetMapping("/user/{age}")@ResponseBodypublic UserVO getUser(@PathVariable Integer age) {log.info("开始查询用户age={}",age);UserVO userVO=new UserVO();userVO.setAge(age);return userVO;}

编辑UserVO类

(1)在UserVO类上加注解：@ApiModel(description = "用户VO")，描述该对象说明.

(2)在UserVO属性上加注解：@ApiModelProperty(value = "用户id",required = true)

@ApiModel(description = "用户VO")@Datapublic class UserVO {        @ApiModelProperty(value = "用户名称",required = true)        String userName;        @ApiModelProperty(value = "用户密码")        String password;        @ApiModelProperty(value = "用户年龄")        Integer age;}

重新启动服务，访问以上接口文档地址，显示以下效果

显示了接口信息，多了个接口

注解描述对应生成接口描述说明

属性描述对应说明

响应接口对象描述说明

经过以上图片展示，接口显示的很丰富，心里爽吧，重新测试提交数据，如果出现以下异常

2020-10-26 19:42:02.487 WARN 15916 --- [nio-8080-exec-4] i.s.m.p.AbstractSerializableParameter : Illegal DefaultValue null for parameter type integerjava.lang.NumberFormatException: For input string: ""at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65) ~[na:1.8.0_92]at java.lang.Long.parseLong(Long.java:601) ~[na:1.8.0_92]at java.lang.Long.valueOf(Long.java:803) ~[na:1.8.0_92]

添加依赖包，重启服务即可解决

io.swaggerswagger-models1.5.21

到目前为止，swagger2接口使用已全部完成。

现在大家看这个接口文档网友是不是很友好，这种页面风格都是老外喜欢的，在中国不喜欢这样的页面，于是国内的工程师们整合了一套符合咱们的接口文档，废话不多说，整合com.github.xiaoymin，加入以下依赖包即可。

com.github.xiaoyminswagger-bootstrap-ui1.9.2

重启服务，访问如下地址，就看到新的api页面了

http://localhost:8080/doc.html

新UI页面

Swagger2注解说明

@Api：使用在类上，一般就是Controller类，属性tags="描述Api说明"@ApiOperation：使用在方法上，构造参数或者value="简单描述接口"，notes="详细使用说明"@ApiImplicitParam：使用在方法上，name="参数名称",value="参数名称描述"，required="参数请求是否必须，默认false"@ApiImplicitParams：使用在方法上，对多个参数定义说明{@ApiImplicitParam(name="参数名称",value="参数名称描述"，required="参数请求是否必须，默认false")}@ApiModel：使用在model类上，description="描述model说明"@ApiModelProperty：使用在model类的属性上，value = "字段描述"，required = "参数请求是否必须，默认false"@ApiResponses：使用在方法请求响应上(很少用){@ApiResponse：使用在方法请求响应上，code="描述状态码：如999服务内部错误"，message="响应描述"}

总结

经过springboot整合swagger2技术文档，一个快速生成api接口文档产生了，大大的提高了我们工作效率，是中小型企业快速开发api文档不二选择，再也不用天天加班写接口文档了