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

Swagger

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

集成Swagger管理API文档

项目中集成Swagger

　　首先是添加swagger的依赖：


     
         
      
       com.spring4all
          
      
       swagger-spring-boot-starter
          
      
       1.9.0.RELEASE

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

@EnableSwagger2Doc@SpringBootApplicationpublic 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
     
       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 = {"学生信息接口"})@RestControllerpublic 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://www.cnblogs.com/MrSaver/p/11546403.html

你可能感兴趣的文章