对于开发人员来说，维护接口文档是一件头疼的事情，因为接口会时不时发生变化。这样可能测试人员或者新入职的同事会看到接口文档跟实际接口有出入。而对于开发人员，接口的变化可能不能很快同步到文档中。swagger可以方便的帮我们维护接口文档。swagger的使用非常简单，下面看一下在springboot中的配置。本文中springboot采用2.1.6版本，swagger采用2.8.0

1.引入swagger依赖

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

2.写一个swagger的配置类，如下

@EnableSwagger2
@Configuration
@Profile(value = {"dev"})
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //需要生成api接口的目录，一般是存放controller的目录
                .apis(RequestHandlerSelectors.basePackage("boot.web"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 定义ApiInfo生成函数
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("SpringBoot使用Swagger2维护api文档")
                //联系人信息
                .contact(new Contact("jinjunzhu", "https://blog.csdn.net/zjj2006", "zjj2006forever@163.com"))
                .version("1.0")
                .description("API 描述")
                .build();
    }
}

3.对controller中的的方法和实体类进行配置，这儿的示例是一个UserController中的方法，代码如下：

@Api(value = "用户操作")
@Controller
@RequestMapping("/user")
public class UserController {

	@Resource
	private UserService userService;

	@ApiOperation(value = "根据用户名获取用户", notes="用户名必填")
	@ApiImplicitParam(name = "username", required = true)
	@RequestMapping(value = "/{username}", method = {RequestMethod.GET})
    @ResponseBody
    public String getUser(@PathVariable String username) {
		return userService.getUser(username).getPassword();
    }

	@ApiOperation(value = "保存用户", notes="post请求中请求参数是一个json,包括用户名密码,例如:{\"username\":\"zhangsan\",\"password\":\"123456\"}")
	@ApiImplicitParam(name = "user", required = true)
	@RequestMapping(value = "/saveUser", method = {RequestMethod.POST})
    @ResponseBody
    public String saveUser(@RequestBody User user) {
		try {
			userService.insert(user);
			return "success!";
		} catch (Exception e) {
			return "failure!";
		}
    }
}

@ApiModel("用户实体类")
public class User implements Serializable{

	private static final long serialVersionUID = 1L;
	
	private Long id;
	@ApiModelProperty("用户名")
	private String username;
	@ApiModelProperty("密码")
	private String password;
	public Long getId() {
		return id;
	}
	public void setId(Long id) {
		this.id = id;
	}
	public String getUsername() {
		return username;
	}
	public void setUsername(String username) {
		this.username = username;
	}
	public String getPassword() {
		return password;
	}
	public void setPassword(String password) {
		this.password = password;
	}
}

@ApiOperation是一个接口说明
@ApiImplicitParam代表一个单一的参数 

配置好后，启动工程，在浏览器输入：http://localhost:8080/swagger-ui.html#/，返回页面如下：

 下面我们重点看saveUser方法，

点击页面上的“Try it out”，输入参数，点击“Execute”，用户信息保存成功。

4.在生产环境中，我们必须禁用swagger，以避免不必要的麻烦。有2种方法可以做到禁用swagger，推荐第一种

1）在SwaggerConfig中增加注解@Profile(value = {"dev"})，同时在application.properties文件中增加：

开发环境spring.profiles.active=dev
生产环境spring.profiles.active=pro
测试环境spring.profiles.active=test

这样就只有开发环境可以使用swagger

2）在SwaggerConfig中增加注解@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")，同时在application.properties文件中增加：

开发环境swagger.enable=true
生产环境swagger.enable=false
测试环境swagger.enable=false

这样就只有开发环境可以使用swagger

源码地址:https://github.com/jinjunzhu/spring-boot-mybatis

欢迎关注个人公众号，共同学习，共同成长