用swagger为springboot生成接口文档

一、为什么要用swagger，它解决了什么问题？

　　随着sprnigboot、springc loud等微服务的流行，在微服务的设计下，小公司微服务小的几十，大公司大的几百上万的微服务。这么多的微服务必定产生了大量的接口调用。而接口的调用就必定要写接口文档。在微服务的盛行下，成千上万的接口文档编写，不可能靠人力来编写，故swagger就产生了，它采用自动化实现并解决了人力编写接口文档的问题。它通过在接口及实体.上添加几个注解的方式就能在项目启动后自动化生成接口文档。

　　Swagger提供了一个全新的维护API文档的方式，有4大优点:
1.自动生成文档：只需要少量的注解，Swagger 就可以根据代码自动生成API文档,很好的保证了文档的时效性。
2.跨语言性，支持40多种语言。
3. Swagger UI呈现出来的是一份可交互式的API 文档，我们可以直接在文档页面尝试API的调用，省去了准备复杂的调用参数的过程。
4.还可以将文档规范导入相关的工具(例如SoapUI) ,这些工具将会为我们自动地创建自动化测试。

二、把springboot的接口，自动生成接口文档

1.配置依赖包pom.xml文件

        <!-- swagger的依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger的管理UI页面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

 

2.修改配置文件application.properties

#表示是否开启swagger，一般线上环境是关闭的
spring.swagger2.enabled=true

3.增加一个swagger配置类

@Configuration
@EnableSwagger2 //启用Swagegr2
public class Swagger2Config {
    /**
     * 在IOC容器里面创建可以对象可以监控Controller里面的是否有Swagger相关的注解
     * 如果，swagger会生成相关的文档
     * @return
     */
    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2).select()
    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }
}

体验地址：http://127.0.0.1:8888/swagger-ui.html

三、案例

/**
 * 用户控制器
 * @author Administrator
 *
 */
@RestController
@RequestMapping("user")
@Api(tags = {"用户管理"},description = "用户数据操作",
        value = "用户管理2")
public class UserCtroller {
    
    /**
     * 添加用户
     */
    @ApiOperation(value = "新增用户",notes="新增注册")
    //consumes = MediaType.APPLICATION_JSON_VALUE  标记前台传过来
    //如果不加consumes，应该数据拼接在url接口后面,参数不能加@RequestBody
    @PostMapping(value= {"addUser"},consumes = MediaType.APPLICATION_JSON_VALUE)
    public Map<String, Object>  addUser(@RequestBody User user){
        Map<String, Object> map = new HashMap<>();
        map.put("msg", "添加成功");
        map.put("code", 1);
        return map;
    }
    
    /**
     * 修改用户
     */
    @ApiOperation(value = "修改用户",notes="修改用户")
    @PostMapping(value = {"updateUser"} ,consumes =  MediaType.APPLICATION_JSON_VALUE)
    public Map<String, Object>  updateUser(@RequestBody User user){
        Map<String, Object> map = new HashMap<>();
        map.put("msg", "修改成功");
        map.put("code", 1);
        return map;
    }
    
    /**
     * 删除用户
     */
    @ApiOperation(value = "删除用户",notes="删除用户")
    @DeleteMapping("deleteUser")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户编号", required = true)
        //可以添加多个@ApiImplicitParam
    })
    public Map<String, Object>  deleteUser(@RequestParam("id")Integer id){
        Map<String, Object> map = new HashMap<>();
        map.put("msg", "删除成功");
        map.put("code", 1);
        return map;
    }
    
    /**
     * 查询一个用户
     */
    @ApiOperation(value = "查询用户",notes="查询用户")
    @GetMapping("queryUserById")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户编号", required = true)
        //可以添加多个@ApiImplicitParam
    })
    public User  queryUserById(@RequestParam("id") Integer id){
        return new User(1, "小明", "武汉",22);
    }
    
    /**
     * 查询所有用户
     */
    @ApiOperation(value = "查询所有用户",notes="查询所有用户")
    @GetMapping("queryAll")
    public List<User>  queryAll(){
        List<User> users = new ArrayList<>();
        for (int i = 1; i <=10; i++) {
            users.add(new User(i, "王五"+i, "武汉"+i, i+20));
        }
        return users;
    }
}

 

常用注解：

swagger常用注解
注解	用途	注解位置
@Api	描述类的作用	注解于类上
@ApiOperation	描述类的方法的作用	注解于方法上
@ApiParam	描述类方法参数的作用	注解于方法的参数上
@ApiModel	描述对象的作用	注解于请求对象或者返回结果对象上
@ApiModelPropert	描述对象里字段的作用	注解于请求对象或者返回结果对象里的字段上