Spring Boot集成springfox-swagger2构建restful API的方法教程

前言

之前跟大家分享了Spring MVC集成springfox-swagger2构建restful API，简单写了如何在springmvc中集成swagger2。这边记录下在springboot中如何集成swagger2。其实使用基本相同。

方法如下：

首先还是引用相关jar包。我使用的maven，在pom.xml中引用相关依赖(原来我使用的是2.2.0的，现在使用2.4.0的)：

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

第二步就是创建swagger的配置类：

这个配置类和springmvc的写法完全一致。为了区分我又重命名一个。

package com.xingguo.springboot;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class Swagger2Configuration {
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(buildApiInf())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xingguo.springboot.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo buildApiInf(){
return new ApiInfoBuilder()
.title("xingguo大标题")
.description("springboot swagger2")
.termsOfServiceUrl("http://blog.csdn.net/u014231523网址链接")
.contact(new Contact("diaoxingguo", "http://blog.csdn.net/u014231523", "diaoxingguo@163.com"))
.build();
}
}

在原来2.2.0的版本中使用

new ApiInfo()

的方法已经过时，使用

new ApiInfoBuilder()

进行构造，需要什么参数就添加什么参数。当然也可以什么都添加。如：

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

那么页面显示的效果如图：

使用new ApiInfoBuilder().build()；

添加属性：

点击

ApiInfoBuilder.Java

的源码可以看到相关方法使用。

第三步就是在自己的controller添加相关的注解：

原来使用在类上使用

@controller

，现在可以使用

@RestController

，然后方法的

@ResponseBody

就可以不用写了，因为

@RestController

的注解接口上已经添加了，要求版本在4.0.1之后。

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
/**
* The value may indicate a suggestion for a logical component name,
* to be turned into a Spring bean in case of an autodetected component.
* @return the suggested component name, if any
* @since 4.0.1
*/
String value() default "";
}

常用的注解如下：

      -

@Api()

用于类名

      -

@ApiOperation()

用于方法名

      -

@ApiParam()

用于参数说明

      -

@ApiModel()

用于实体类

      -

@ApiModelPropert

y用于实体类属性

更加详细的含义可以参考官方说明wiki

下面会用代码和示例图说明。

第四部就是在启动项目在浏览器上输入url:

http://{ip}:{port}/swagger-ui.html#/

我在

application.properties

中设置的自己的端口号为9090(如果不设置，默认为8080)

server.port=9090

所以我的url是：

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

如图：

这里会把相应包下的所有controller按类进行显示。

我们看下其中一个类

UserController.java

,（请忽略业务逻辑，只看注解）

package com.xingguo.springboot.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import javax.annotation.Resource;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;
import com.xingguo.springboot.model.User;
import com.xingguo.springboot.service.UserService;
/**
* Created by diaoxingguo on 2016/10/24.
*/
@Api(value="用户controller",description="用户操作",tags={"用户操作接口"})
@RestController
public class UserController {
@Resource
private UserService userService;
@ApiOperation("获取用户信息")
@GetMapping("/getUserInfo")
public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) {
User user = userService.getUserInfo();
return user;
}
@ApiOperation("更改用户信息")
@PostMapping("/updateUserInfo")
public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){
int num = userService.updateUserInfo(user);
return num;
}
@ApiOperation("添加用户信息")
@PostMapping("/saveUser")
public String saveUser(@RequestBody @ApiParam(name="user",value="json fromat",required=true) User user) {
userService.saveUser(user);
return "success";
}
}

这里说明下，在使用对象作为参数时，可以在对象上添加相应的注解，用户页面显示。

如：

package com.xingguo.springboot.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
/**
* Created by diaoxingguo on 2016/10/24.
*/
@ApiModel(description="用户对象user")
public class User {
@ApiModelProperty(value="用户名",name="username")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
private String nickName;
private Integer isDeleted;
private String[] ids;
private List<String> idList;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public Integer getState() {
return state;
}
public void setState(Integer state) {
this.state = state;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
public String[] getIds() {
return ids;
}
public void setIds(String[] ids) {
this.ids = ids;
}
public List<String> getIdList() {
return idList;
}
public void setIdList(List<String> idList) {
this.idList = idList;
}
public String getNickName() {
return nickName;
}
public void setNickName(String nickName) {
this.nickName = nickName;
}
public Integer getIsDeleted() {
return isDeleted;
}
public void setIsDeleted(Integer isDeleted) {
this.isDeleted = isDeleted;
}
}

显示的效果如图：

看上图红框的部分，其中一个是json格式的点击就可以获取参数格式。

第二张中可以看到字段相应的注释和是否必填。

如果在字段上添加注释

@ApiModelProperty(required=true)

就是必填（默认是false），相应的页面optional标识也会消失，标识这个字段必填。

点击下面的try it out按钮就可以进行调试。

在使用单个参数时，如上面代码中的

getUserInfo（）

方法，对应的效果图如下：

这里如果是添加

required=true

，

@ApiParam(required=true)

则会在页面上显示required的标识。同样默认为false。

其他的使用方式可以自己动手试试。

总结

以上就是这篇文章的全部内容了，希望本文的内容对大家的学习或者工作能带来一定的帮助，如有疑问大家可以留言交流，谢谢大家对脚本之家的支持。

您可能感兴趣的文章:

• SpringBoot配置SwaggerUI访问404错误的解决方法
• SpringBoot集成Swagger2实现Restful(类型转换错误解决办法)
• spring boot整合Swagger2的示例代码
• springboot + swagger 实例代码
• Spring Boot 整合mybatis 与 swagger2
• Spring Boot集成Swagger2项目实战
• Spring Boot 项目中使用Swagger2的示例
• SpringBoot集成swagger的实例代码
• Springboot中集成Swagger2框架的方法
• Spring Boot整合Swagger2的完整步骤详解