Swagger

1.Swagger项目

项目部分代码，只展示与Swagger相关

1）在pom.xml文件中添加swagger

<!--swagger依赖添加-->
       <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        
 <!--swagger界面工具-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>2.0.9</version>
        </dependency>

2）配置swagger

package com.example.sdv.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.sdv.controller"))     //添加controller的映射路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("实现从数据库里面拿取数据")
                .termsOfServiceUrl("www.baidu.com")
                .version("1.0")
                .build();
    }
}

3）在controller中使用swagger

package com.example.sdv.controller;


import com.example.sdv.entity.UserDO;
import com.example.sdv.service.UserDoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.*;

@RestController
public class UserController {

    @Autowired
    UserDoService userDoService;

    /**
     * 根据ID查询用户
     *
     * @param id
     * @return
     */
    @ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    public UserDO getUserById(@PathVariable(value = "id") Integer id) {
        return userDoService.getUserInfo(id);
    }

    /**
     * 查询用户列表
     *
     * @return
     */
    @ApiOperation(value = "获取用户列表", notes = "获取用户列表")
    @RequestMapping(value = "users", method = RequestMethod.GET)
    public List<UserDO> getUserList() {

        return userDoService.selectAll();
    }

    /**
     * 添加用户
     *
     * @param user
     * @return
     */
    @ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "UserDO")
    @RequestMapping(value = "user", method = RequestMethod.POST)
    public int add(@RequestBody UserDO user) {
        return userDoService.save(user);
    }

    /**
     * 根据id删除用户
     *
     * @param id
     * @return
     */
    @ApiOperation(value = "删除用户", notes = "根据url的id来指定删除用户")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    public String delete(@PathVariable(value = "id") Integer id) {
        int result = userDoService.deleteById(id);
        if (result >= 1) {
            return "删除成功！";
        } else {
            return "删除失败！！";
        }
    }
}

4）启动类（配置允许Swagger2）

package com.example.sdv;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.scheduling.annotation.EnableScheduling;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
@ComponentScan(basePackages = "com.example.sdv.*")
@MapperScan(basePackages = "com.example.sdv.dao.*")
@EnableCaching
@EnableScheduling
public class SdvApplication {

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

5）跑起来的效果

提醒：在不使用knife4j的情况下，登录使用的地址是：localhost:端口号/swagger-ui.html#/
      使用knife4j登录的地址是：                localhost:端口号/doc.html#/

2.Swagger

2.1 swagger 概念

swagger是一个简单的Restful API文档生成管理工具，根据我们自己的配置信息能够自动生成、描述、调用和可视化restful风格并且实时更新的web服务，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。官方地址

2.2 swagger 常用注解

a) @Api：用于类上，说明该类的作用

@Api(tags = "测试")
public class UserController {}        //说明该类的作用是用于测试

b）@ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义

@ApiOperation(
          value = "Find purchase order by ID",
          notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
          response = Order,
          tags = {"Pet Store"})

c) @ApiParam请求属性

public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)

d) @ApiResponse：响应配置

@ApiResponse(code = 400, message = "Invalid user supplied")

e) @ApiResponses ：响应集配置

 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

f) @ApiImplicitParams：用在方法上包含一组参数说明

  @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "UserDO")
    })

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

@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")

h) @ApiModel ：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候；

@Data
@ApiModel   // 在实体类上边使用，标记类时swagger的解析类
public class UserDTO{
  @ApiModelProperty("姓名")
  private String name;
  @ApiModelProperty("年龄")
  private Integer age;
}

i) @ApiModelProperty：描述一个model的属性

 @ApiModelProperty(value = "id",example = "111")
     private int id=111;   //在swagger界面上 id的example值为111

f) @ResponseHeader ： 响应头设置

@ResponseHeader(name="head1",description="response head conf")