API文档工具——Swagger

1.Swagger概念

　　a.描述：Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

　　b.作用：

　　　　1）接口的文档在线自动生成

　　　　2）功能测试

　　c.注解：

　　　　1）@ApiModel：用于类，表示对类进行说明，用于参数用实体类接收

　　　　　　·value：表示对象名

　　　　　　·description：描述

　　　　2）@ApiModelProperty：用于方法，字段；表示对model属性的说明或者数据操作更改

　　　　　　·value：字段说明

　　　　　　·name：重写属性名字

　　　　　　·dataType：重写属性类型

　　　　　　·required：是否必填

　　　　　　·example：举例说明

　　　　　　·hidden：隐藏

　　　　3）@Api：修饰整个类，描述Controller的作用

　　　　　　·tags：控制类功能说明，tags是一个字符串数组，可以添加多个标签

　　　　　　·value：也是说明，可以使用tags替代

　　　　4）@ApiOperation：描述一个类的一个方法，或者说一个接口

　　　　　　·value：用于方法描述

　　　　　　·notes：用于提示内容

　　　　　　·tags：可以重新分组

　　　　5）@ApiParam：单个参数描述

　　　　　　·name：参数名

　　　　　　·value：参数说明

　　　　　　·required：是否必填

　　　　6）@ApiImplicitParams、@ApiImplicitParam：用于方法，描述方法的参数（@ApiImplicitParams包含多个@AplimplicitParam）

　　　　　　·name：参数名

　　　　　　·value：参数说明

　　　　　　·dataType：数据类型

　　　　　　·paramType：参数类型

　　　　　　·example：举例说明

　　　　7）@ApiIgnore：用于类或者方法上，可以不被swagger显示在页面上

2.Spring整合Swagger

　　a.在数据库创建`t_user`用户表

-- 用户表
CREATE TABLE `t_user` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `user_name` varchar(255) NOT NULL,
  `user_pwd` varchar(255) NOT NULL,
  PRIMARY KEY (`id`)
);

　　b.导入maven依赖

  <properties>

      ......

      <!-- spring -->
      <spring.version>5.1.1.RELEASE</spring.version>
      <!-- jackson-json -->
      <jackson.version>2.9.4</jackson.version>
      <!-- log4j -->
      <slf4j.version>1.7.18</slf4j.version>
      <log4j.version>1.2.17</log4j.version>
  </properties>

  <dependencies>
      <!-- spring -->
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-core</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-webmvc</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-oxm</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-tx</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-aop</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-context-support</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-test</artifactId>
          <version>${spring.version}</version>
      </dependency>

      <!-- Jackson -->
      <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-core</artifactId>
          <version>${jackson.version}</version>
      </dependency>
      <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-databind</artifactId>
          <version>${jackson.version}</version>
      </dependency>
      <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-annotations</artifactId>
          <version>${jackson.version}</version>
      </dependency>

      <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.12</version>
          <scope>test</scope>
      </dependency>

      <!-- AOP -->
      <dependency>
          <groupId>org.aspectj</groupId>
          <artifactId>aspectjrt</artifactId>
          <version>1.8.6</version>
      </dependency>
      <dependency>
          <groupId>org.aspectj</groupId>
          <artifactId>aspectjweaver</artifactId>
          <version>1.8.6</version>
      </dependency>

      <!-- 日志相关 -->
      <dependency>
          <groupId>log4j</groupId>
          <artifactId>log4j</artifactId>
          <version>${log4j.version}</version>
      </dependency>
      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-api</artifactId>
          <version>${slf4j.version}</version>
      </dependency>
      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-log4j12</artifactId>
          <version>${slf4j.version}</version>
      </dependency>

      <!-- servlet -->
      <dependency>
          <groupId>javax.servlet</groupId>
          <artifactId>javax.servlet-api</artifactId>
          <version>4.0.1</version>
          <scope>provided</scope>
      </dependency>
      <dependency>
          <groupId>javax.servlet.jsp</groupId>
          <artifactId>jsp-api</artifactId>
          <version>2.2</version>
          <scope>provided</scope>
      </dependency>

      <!-- spring-jdbc -->
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-jdbc</artifactId>
          <version>${spring.version}</version>
      </dependency>
      <!-- MySQL -->
      <dependency>
          <groupId>mysql</groupId>
          <artifactId>mysql-connector-java</artifactId>
          <version>8.0.13</version>
      </dependency>
      <!-- 连接池 -->
      <dependency>
          <groupId>com.alibaba</groupId>
          <artifactId>druid</artifactId>
          <version>1.1.12</version>
      </dependency>

      <!-- mp 依赖 -->
      <dependency>
          <groupId>com.baomidou</groupId>
          <artifactId>mybatis-plus</artifactId>
          <version>3.2.0</version>
      </dependency>

      <!-- swagger -->
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger2</artifactId>
          <version>2.7.0</version>
      </dependency>
      <dependency>
          <groupId>io.springfox</groupId>
          <artifactId>springfox-swagger-ui</artifactId>
          <version>2.7.0</version>
      </dependency>
  </dependencies>

　　2.创建 spring.xml 配置文件

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:aop="http://www.springframework.org/schema/aop"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">

    <!-- 自动扫描的包名 -->
    <context:component-scan base-package="com.wode" />

    <!-- 开启AOP代理 -->
    <aop:aspectj-autoproxy proxy-target-class="true" />

    <!--开启注解处理器 -->
    <context:annotation-config />

    <context:property-placeholder location="classpath:jdbc.properties"/>
    <!-- Spring中引入其他配置文件 -->
    <import resource="classpath*:/spring-mybatis.xml" />

</beans>

　　3.创建 spring-mybatis.xml 配置文件

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-4.3.xsd">

    <!-- 开启注解声明式事务 -->
    <tx:annotation-driven/>

    <!-- 数据源 -->
    <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource">
        <property name="driverClassName" value="${jdbc.driver}"/>
        <property name="url" value="${jdbc.url}"/>
        <property name="username" value="${jdbc.username}"/>
        <property name="password" value="${jdbc.password}"/>
    </bean>

    <!-- mybatits-plus 整合 Spring -->
    <bean id="sqlSessionFactory" class="com.baomidou.mybatisplus.extension.spring.MybatisSqlSessionFactoryBean">
        <!-- 加载数据源 -->
        <property name="dataSource" ref="dataSource" />
        <!-- 指定 pojo 目录 -->
        <property name="typeAliasesPackage" value="com.wode.entity"/>
        <!-- mybatis-plus 插件 -->
        <property name="plugins">
            <array>
                <!-- 分页插件 -->
                <bean class="com.baomidou.mybatisplus.extension.plugins.PaginationInterceptor"></bean>
            </array>
        </property>
        <!-- 加载 mybatis-plus 全局属性 -->
        <property name="globalConfig" ref="globalConfig" />
    </bean>

    <!-- 配置和 mybatis-plus 全局属性 -->
    <bean id="globalConfig" class="com.baomidou.mybatisplus.core.config.GlobalConfig">
        <property name="dbConfig" ref="dbConfig"/>
    </bean>
    <bean id="dbConfig" class="com.baomidou.mybatisplus.core.config.GlobalConfig.DbConfig">
        <!--
             AUTO -> 数据库ID自增
             INPUT -> 用户输入ID
             ID_WORKER -> 全局唯一ID
             UUID -> 全局唯一ID
          -->
        <property name="idType" value="AUTO"/>
        <!-- 全局的表前缀策略配置 -->
        <property name="tablePrefix" value="t_" />
    </bean>

    <!-- mybatis 的动态代理 -->
    <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
        <property name="basePackage" value="com.wode.dao" />
        <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
    </bean>

    <!-- 事务代理管理器 -->
    <bean name="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
        <property name="dataSource" ref="dataSource" />
    </bean>
</beans>

　　4.创建 jdbc.properties 配置文件

jdbc.driver=com.mysql.jdbc.Driver
jdbc.url=jdbc:mysql://localhost:3306/mytest?useUnicode=true&characterEncoding=utf-8&useSSL=true&serverTimezone=UTC
jdbc.username=root
jdbc.password=123456

　　5.创建 spring-mvc.xml 配置文件

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/context
    http://www.springframework.org/schema/context/spring-context.xsd
    http://www.springframework.org/schema/mvc
    http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
    <!-- 开启SpringMVC注解模式 -->
    <mvc:annotation-driven />

    <!-- 扫描web相关的bean -->
    <context:component-scan base-package="com.wode.controller" />

    <!-- 静态资源默认servlet配置 -->
    <mvc:default-servlet-handler/>

    <!-- swagger配置类 -->
    <bean class="com.wode.config.SwaggerConfig" />

    <!-- 配置jsp 显示ViewResolver -->
    <bean class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="viewClass" value="org.springframework.web.servlet.view.JstlView" />
        <property name="prefix" value="/WEB-INF/page/" />
        <property name="suffix" value=".jsp" />
    </bean>

</beans>

　　6.配置 web.xml 配置文件

<!DOCTYPE web-app PUBLIC
 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd" >

<web-app>
  <display-name>Archetype Created Web Application</display-name>

  <!-- 欢迎界面 -->
  <welcome-file-list>
    <welcome-file>index.jsp</welcome-file>
  </welcome-file-list>

  <!-- 加载Spring配置文件 -->
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>classpath:spring.xml</param-value>
  </context-param>

  <!-- SpringMvc监听Spring配置 -->
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>

  <!-- 通过xml加载SpringMvc的DispatcherServlet -->
  <servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>classpath:spring-mvc.xml</param-value>
    </init-param>
  </servlet>
  <servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
  </servlet-mapping>

  <!-- 编码过滤器 -->
  <filter>
    <filter-name>encodingFilter</filter-name>
    <filter-class>
      org.springframework.web.filter.CharacterEncodingFilter
    </filter-class>
    <init-param>
      <param-name>encoding</param-name>
      <param-value>UTF-8</param-value>
    </init-param>
    <init-param>
      <param-name>forceEncoding</param-name>
      <param-value>true</param-value>
    </init-param>
  </filter>
  <filter-mapping>
    <filter-name>encodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
</web-app>

　　7.创建Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("对外开放接口API 文档")               //大标题 title
                .description("HTTP对外开放接口")             //小标题
                .version("1.0.0")                           //版本
                .termsOfServiceUrl("http://xxx.xxx.com")    //终端服务程序
                .license("LICENSE")                         //链接显示文字
                .licenseUrl("http://xxx.xxx.com")           //网站链接
                .build();
    }

}

　　8.创建Entity实体类

@ApiModel("用户") //@ApiModel用于类，表示对类进行说明，用于参数用实体类接收
@TableName
//@TableName("t_user")
public class User {

    @ApiModelProperty(value="用户ID") //@ApiModelProperty用于方法，字段；表示对model属性的说明或者数据操作更改
    @TableId
    private int id;
    @ApiModelProperty(value="用户名", required=true)
    private String userName;
    @ApiModelProperty(value="密码", required=true)
    private String userPwd;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getUserPwd() {
        return userPwd;
    }

    public void setUserPwd(String userPwd) {
        this.userPwd = userPwd;
    }
}

　　9.创建DAO

public interface UserMapper extends BaseMapper<User> {
}

　　10.创建Service

@Service
public class UserService {

    @Resource
    private UserMapper userMapper;

    public boolean addUser(User user){
        if(userMapper.insert(user) > 0){
            return true;
        }
        return false;
    }

    public boolean updateUser(User user){
        if(userMapper.updateById(user) > 0){
            return true;
        }
        return false;
    }

    public User getUser(int id){
        return userMapper.selectById(id);
    }

    public IPage<User> getUserList(int currentPage, int pageSize){
        Page<User> page = new Page<>(currentPage, pageSize);
        QueryWrapper<User> queryWrapper = new QueryWrapper<>();
        return userMapper.selectPage(page, queryWrapper);
    }

    public boolean deleteUser(int id){
        if(userMapper.deleteById(id) > 0){
            return true;
        }
        return false;
    }

}

　　11.创建Controller

@RestController
@RequestMapping("/user")
@Api(tags="用户接口")    //@Api修饰整个类，描述Controller的作用
public class UserController {

    @Resource
    private UserService userService;


    @ApiOperation(value="value:添加用户", notes="notes:添加用户", tags="添加")   //@ApiOperation描述一个类的一个方法，或者说一个接口
    @PostMapping("/add")
    public String addUser(User user) {
        if(userService.addUser(user)){
            return "Success";
        }
        return "Failure";
    }


    @ApiOperation(value="修改用户", notes="修改用户", tags="修改")
    @PostMapping("/update")
    public String updateUser(User user) {
        if(userService.updateUser(user)){
            return "Success";
        }
        return "Failure";
    }


    @ApiOperation(value="获取用户详情", notes="获取用户详情", tags="查询")
    @ApiImplicitParam(name="id", value="用户ID", dataType="int", required=true, paramType="path")   //@ApiImplicitParam用于方法，描述方法的参数
    @GetMapping("/get/{id}")
    public User getUser(@PathVariable("id") int id) {
        return userService.getUser(id);
    }


    @ApiOperation(value="获取用户列表", notes="获取用户列表", tags="查询")
    @ApiImplicitParams({    //@ApiImplicitParams用于方法，描述方法的参数(多个)
            @ApiImplicitParam(name="currentPage", value="当前页数", dataType="int", required=true, paramType="query"),
            @ApiImplicitParam(name="pageSize" , value="每页条数" , dataType="int", required=true, paramType="query")
    })
    @GetMapping("/list")
    public IPage<User> getUserList(int currentPage, int pageSize){
        return userService.getUserList(currentPage, pageSize);
    }


//    @ApiIgnore  //@ApiIgnore用于类或者方法上，可以不被swagger显示在页面上
    @ApiOperation(value="删除用户", notes="删除用户", tags="删除")
    @GetMapping("/delete/{id}")
    public String deleteUser(@ApiParam(name="id", value="用户ID", required=true) @PathVariable("id") int id){ //@ApiParam单个参数描述
        if(userService.deleteUser(id)){
            return "Success";
        }
        return "Failure";
    }

}

　　12.访问 http://localhost:8080/（项目名）/swagger-ui.html 测试