SpringBoot 2.0 学习（十一）集成Swagger在线调试

SpringBoot 2.0 学习（十一）集成Swagger在线调试

Swagger是什么？

Swagger是一款Restful接口的API文档在线生成+功能测试软件，它是一个规范且完整的框架，用于生成，描述，调用和可视化的restful风格的web服务。前端和后端唯一联系，变成了API接口；API文档自然就成前后端开发人员联系的纽带，变得尤为的重要，swagger就是一款让你更好的书写API文档的框架。

具体操作

第一步：添加依赖

	<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
     <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>
    
    <!--lombok依赖 -->
	<dependency>
	    <groupId>org.projectlombok</groupId>
	    <artifactId>lombok</artifactId>
	    <version>1.18.4</version>
	    <scope>provided</scope>
	</dependency>

第二步：配置文件
配置spring.swagger.enabled开启swagger的使用，如果在生产环境中不想用可以在对应的profile下面将它设置为spring.swagger.enabled=false，这样一来接口就不存在暴露的风险

# 扫描的包路径,默认扫描所有
spring.swagger.base-package=com.winterchen
# 默认为 true
spring.swagger.enabled=true

第三步：实体类
注解解释：

• @Data 自动生成set/get方法

• @AllArgsConstructor 自动生成所有有参的构造方法

• @NoArgsConstructor 自动生成无参的构造方法
  
  第四步：restful风格接口

   @RestController
   @RequestMapping("/users")
   @Api(tags = {"用户管理"}, value = "用户管理")
   public class UserController {
  
   		private static final Logger log = LoggerFactory.getLogger(UserController.class);
  
   		@GetMapping
   		@ApiOperation(value = "条件查询（DONE）")
   		@ApiImplicitParams({
       			@ApiImplicitParam(name = "username", value = "用户名", dataType = "String", paramType = "query"),
       			@ApiImplicitParam(name = "password", value = "密码", dataType = "String", paramType = "query"),
   		})
   		
   		public User query(String username, String password) {
   				log.info("多个参数用  @ApiImplicitParams");
  					return new User(1L, username, password);
   		}
  
   	    @GetMapping("/{id}")
   	    @ApiOperation(value = "主键查询（DONE）")
          @ApiImplicitParams({
        		 @ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long", paramType = "path"),
   	    })
   	 
   	    public User get(@PathVariable Long id) {
                  log.info("单个参数用  @ApiImplicitParam");
                  return new User(id, "u1", "p1");
          }
  
          @DeleteMapping("/{id}")
          @ApiOperation(value = "删除用户（DONE）")
          @ApiImplicitParam(name = "id", value = "用户编号", dataType = "Long", paramType = "path")
          public void delete(@PathVariable Long id) {
                log.info("单个参数用 ApiImplicitParam");
          }
  
          @PostMapping
          @ApiOperation(value = "添加用户（DONE）")
          public User post(@RequestBody User user) {
                log.info("如果是 POST PUT 这种带 @RequestBody 的可以不用写 @ApiImplicitParam");
                return user;
          }
  
          @PutMapping("/{id}")
          @ApiOperation(value = "修改用户（DONE）")
          public void put(@PathVariable Long id, @RequestBody User user) {
                log.info("如果你不想写 @ApiImplicitParam 那么 swagger 也会使用默认的参数名作为描述信息 ");
          }
         
  }
  

第五步：启动类

第六步：效果展示
需要打开浏览器输入http://localhost:8080/swagger-ui.html，更多操作请自行体验…

Swagger2注解解释

• @Api：用在请求的类上，表示对类的说明

    tags="说明该类的作用，可以在UI界面上看到的注解"
    value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
  

• @ApiOperation：用在请求的方法上，说明方法的用途、作用

    value="说明方法的用途、作用"
    notes="方法的备注说明"
  

• @ApiImplicitParams：用在请求的方法上，表示一组参数说明

• @ApiImplicitParam：在@ApiImplicitParams注解中，指定一个请求参数的各个方面

    name：参数名
    value：参数的汉字说明、解释
    required：参数是否必须传
    paramType：参数放在哪个地方
        · header --> 请求参数的获取：@RequestHeader
        · query --> 请求参数的获取：@RequestParam
        · path（用于restful接口）--> 请求参数的获取：@PathVariable
        · body（不常用）
        · form（不常用）    
    dataType：参数类型，默认String，其它值dataType="Integer"       
    defaultValue：参数的默认值
  

• @ApiResponses：用在请求的方法上，表示一组响应

• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

  code：数字，例如400
  message：信息，例如"请求参数没填好"
  response：抛出异常的类
  

• @ApiModelProperty：用在属性上，描述响应类的属性

• @ApiModel：用于响应类上，表示一个返回响应数据的信息
  （这种一般用在post创建的时候，使用@RequestBody这样的场景，
  请求参数无法使用@ApiImplicitParam注解进行描述的时候）

文章参考
https://blog.csdn.net/jiangyu1013/article/details/83107255
https://blog.csdn.net/Winter_chen001/article/details/80748253#commentBox