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 測試