springboot研究八：springboot使用swagger自动构建api

最新推荐文章于 2024-07-08 17:19:32 发布

君哥聊技术

最新推荐文章于 2024-07-08 17:19:32 发布

阅读量328

点赞数

分类专栏： spring-boot

本文链接：https://blog.csdn.net/zjj2006/article/details/105970558

版权

spring-boot 专栏收录该内容

15 篇文章 4 订阅

订阅专栏

对于开发人员来说，维护接口文档是一件头疼的事情，因为接口会时不时发生变化。这样可能测试人员或者新入职的同事会看到接口文档跟实际接口有出入。而对于开发人员，接口的变化可能不能很快同步到文档中。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#/，返回页面如下：