SpringBoot学习笔记：Swagger实现文档管理

Swagger

　　Swagger是一个规范且完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger的目标是对REST API定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。

集成Swagger管理API文档

项目中集成Swagger

　　首先是添加swagger的依赖：

<!--swagger-spring-boot-starter -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

　　接着，在启动类中添加@EnableSwagger2Doc注解开启Swagger，如下：

@EnableSwagger2Doc
@SpringBootApplication
public class Application {

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

使用Swagger生成文档

　　Swagger通过注解来生成对应的API，在接口上我们需要加上各种注解来描述这个接口，如

    @ApiOperation(value = " 查找城镇列表 ")
    @ApiResponses({@ApiResponse(code = 200,message = "OK",response = String.class)})
    @RequestMapping(value = "getTownInfoList.do", method = RequestMethod.POST)
    public List<String> getTownInfoList() {
        try {
            return studentMapper.getListGroup("stu_town");
        } catch (Exception e) {
            e.printStackTrace();
        }
        return null;
    }

　　在这里我们使用到了两个注解：

@ApiOperation用在方法上，说明方法的作用，添加notes属性可以详细描述接口信息。
@ApiResponses用在方法上，说明接口响应的一些信息；@ApiResponses封装了多个@ApiResponse，来为不同的响应码设置不同响应信息。

在线测试接口

　　通过 服务器地址:port/swagger-ui.html 来访问Swagger服务，其界面如下：

　　找到刚刚描述的方法，可以查看接口详情，以及尝试接口调用。　　

Swagger注解

　　本节主要描述一些常用的生成接口文档的注解，上面介绍过的就不说了

@Api

　　用在类上，说明该类的作用.

@Api(tags = {"学生信息接口"})
@RestController
public class StudentController {
  ...  
}

@ApiModel

　　用在类上，表示对参数类进行说明。

@ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
public class StudentModel {
    private Integer stu_id;
    private String stu_name;
    private String stu_sex;
    ...  
}

@ApiModedlProperty

　　用在字段上，表示对参数类中的字段进行说明。

@ApiModel(value = "com.ms.qiandao.model.StudentModel",description = "新增用户参数")
public class StudentModel {
    @ApiModelProperty(value = "学生ID")
    private Integer stu_id;
    @ApiModelProperty(value = "学生姓名")
    private String stu_name;
    @ApiModelProperty(value = "学生性别")
    private String stu_sex;
    ...  
}

@ApiParam

　　用于对Controller方法中的参数进行说明。

@RequestMapping("cancel.do")
public RegisterCode getById(@ApiParam(value = "学生id",required = true) Integer id) {
   ...
}

@ApilmplicitParam和@ApilmplicitParams

　　用于方法上，为单独的请求参数进行说明，和@ApiParam差不多，只不过是写在方法上面。

参考资料

《Spring Cloud微服务入门、实战与实践》
https://swagger.io/tools/swagger-ui/