SpringCloud学习笔记（四）整合swagger2，搭建Restful API 在线文档（+整合mybatis+mybatis-generator插件的使用）

   项目地址：https://github.com/gongxianshengjiadexiaohuihui/SpringCloudDemo

   首先我们要对Restful有一定的了解，为了理解这个概念，我还是下了很大功夫，查了很多资料的。

   RESTful架构，就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，所以正得到越来越多网站的采用，REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的，这篇论文影响深远，他是这么介绍他的论文的。

    "本文研究计算机科学两大前沿----软件和网络----的交叉点。长期以来，软件研究主要关注软件设计的分类、设计方法的演化，很少客观地评估不同的设计选择对系统行为的影响。而相反地，网络研究主要关注系统之间通信行为的细节、如何改进特定通信机制的表现，常常忽视了一个事实，那就是改变应用程序的互动风格比改变互动协议，对整体表现有更大的影响。我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。"

•   Represatation  REST的名称"表现层状态转化"中，省略了主语。"表现层"其实指的是"资源"（Resources）的"表现层"。

        所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一          种服务，总之就是一个具体的实在。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获        取这个资    源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

        所谓"上网"，就是与互联网上一系列的"资源"互动，调用它的URI 

       "资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现                              层"（Representation）。

        比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以        用JPG格式表现，也可以用PNG格式表现。

        URI只代表资源的实体，不代表它的形式。严格地说，有些网址最后的".html"后缀名是不必要的，因为这个后缀名表示          格 式，属于"表现层"范畴，而URI应该只代表"资源"的位置。它的具体表现形式，应该在HTTP请求的头信息中用Accept        和Content-Type字段指定，这两个字段才是对"表现层"的描述。

• State transfer 访问一个网站就代表了客户端和服务器的一个互动过程，在这个过程中，势必涉及到数据和状态的变化，互          联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作          服务器，必须通过某种手段，让服务器端发生状态转化，而这种转化是建立在表现层，所以就是“变现层状态转化”。客          户端用到的手段，只能是HTTP协议，具体来说就是HTTP协议里面几种操作数据的方式GET（SELECT）：从服务器取        出资源（一项或多项）。

• • POST（CREATE）：在服务器新建一个资源。
  •  PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
  • PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
  • DELETE（DELETE）：从服务器删除资源。

  还有两个不常用的HTTP动词。

  • HEAD：获取资源的元数据。
  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

      概念讲完了，下面是实例，

      还是前面的例子，我们进行扩充

      首先是项目结构，在eureka-client的项目结构

      

为了方便，我们这次使用mybatis所提供的代码自动生成工具，我们只需要在数据库建好表就可以自动生成实体类，mapper，dao层，

 首先在pom文件中引入插件

            
                org.mybatis.generator
                mybatis-generator-maven-plugin
                1.3.2
                
                    ${basedir}/src/main/resources/mybatis-generator-config.xml
                    true
                    true
                
                
                    
                        org.mybatis.generator
                        mybatis-generator-core
                        1.3.2
                    
                
            

然后就是写mybatis-generator-config.xml

这时我们的maven project的plugins就会有一个mybatis-generator功能，运行即可

大功告成，

这个工具还是很有用的，如果项目很大的话，不可能一个个写，多累人啊。

然后是整合mybatis

需要引入依赖

   
        
            org.mybatis.spring.boot
            mybatis-spring-boot-starter
            1.3.2
            
                
                    org.mybatis
                    mybatis
                
            
        
        
            mysql
            mysql-connector-java
            5.1.25
        
        
            org.mybatis
            mybatis
            3.4.6
        

 

需要配置数据源和xml文件的位置

   client:
     service-url:
       default-zone: http://peer1:8761/eureka/
server:
   port: 8763
spring:
   application:
      name: eureka-client
   datasource:
      url: jdbc:mysql://localhost:3306/ggp?useUnicode=true&characterEncoding=UTF-8&useSSL=false
      username: root
      password: 3220
      driver-class-name: com.mysql.jdbc.Driver
mybatis:
  mapper-locations: classpath:mapping/*.xml

开始整合swagger2，先引入依赖

     
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        

写swagger2的配置类

package com.example.eurekaclient.swagger2;

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;

/**
 * @ClassName Swagger2
 * @Description TODO
 * @Author Mr.G
 * @Date 2018/9/7 14:46
 * @Version 1.0
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi(){
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .select()
                 .apis(RequestHandlerSelectors.basePackage("com.example.eurekaclient.swagger2.controller"))
                 .paths(PathSelectors.any())
                 .build();

    }
    private  ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("利用swagger2构建api文档")
                .description("简单优雅的RestFul风格")
                .version("1.0")
                .build();
    }

}

 

然后写sever层

package com.example.eurekaclient.swagger2.server;

import com.example.eurekaclient.swagger2.entity.User;



/**
 * @ClassName UserService
 * @Description TODO
 * @Author Mr.G
 * @Date 2018/9/7 17:17
 * @Version 1.0
 */
public interface UserService {

    User findUserByName(String name);
    int saveUser(User user);
    int updateUser(User user);
    int deleteUser(String name);


}


package com.example.eurekaclient.swagger2.server.serviceImpl;

import com.example.eurekaclient.swagger2.dao.UserMapper;
import com.example.eurekaclient.swagger2.entity.User;
import com.example.eurekaclient.swagger2.server.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;


/**
 * @ClassName UserServiceImpl
 * @Description TODO
 * @Author Mr.G
 * @Date 2018/9/7 17:19
 * @Version 1.0
 */
@Service
public class UserServiceImpl implements UserService {

    @Autowired
    private UserMapper userMapper;
    @Override
    public User findUserByName(String name) {
        return userMapper.selectByPrimaryKey(name);
    }

    @Override
    public int saveUser(User user) {
        return userMapper.insert(user);
    }

    @Override
    public int updateUser(User user) {
        return userMapper.updateByPrimaryKeySelective(user);
    }

    @Override
    public int deleteUser(String name) {
        return userMapper.deleteByPrimaryKey(name);
    }
}

Controller层

package com.example.eurekaclient.swagger2.controller;

import com.example.eurekaclient.swagger2.entity.User;
import com.example.eurekaclient.swagger2.server.UserService;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

/**
 * @ClassName UserController
 * @Description TODO
 * @Author Mr.G
 * @Date 2018/9/7 17:19
 * @Version 1.0
 */
@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    UserService userService;

    @ApiOperation(value="创建用户",notes="创建用户")
    @RequestMapping(value="",method=RequestMethod.POST)
    public int postUser(@RequestBody User user){
        return userService.saveUser(user);
    }
    @ApiOperation(value="删除用户",notes="删除用户")
    @RequestMapping(value="/{name}",method=RequestMethod.DELETE)
    public int deleteUser(@PathVariable String name){
        return userService.deleteUser(name);
    }
    @ApiOperation(value="更改用户",notes="更改用户")
    @RequestMapping(value="",method=RequestMethod.PUT)
    public int updateUser(@RequestBody User user){
        return userService.updateUser(user);
    }
    @ApiOperation(value = "查找用户",notes="查找用户")
    @RequestMapping(value="/{name}",method=RequestMethod.GET)
    public User getUser(@PathVariable String name){
        return userService.findUserByName(name);
    }
}

到此已经结束了贴出完整的pom文件

    4.0.0

    com.example
    eureka-client
    0.0.1-SNAPSHOT
    jar

    eureka-client
    Demo project for Spring Boot

    
        spring-cloud
        eureka
        1.0-SNAPSHOT
    

    
        
            org.springframework.cloud
            spring-cloud-starter-netflix-eureka-server
        

        
            org.springframework.boot
            spring-boot-starter
        

        
            org.springframework.boot
            spring-boot-starter-test
            test
        
        
            io.springfox
            springfox-swagger2
            2.9.2
        
        
            io.springfox
            springfox-swagger-ui
            2.9.2
        
        
        
            org.mybatis.spring.boot
            mybatis-spring-boot-starter
            1.3.2
            
                
                    org.mybatis
                    mybatis
                
            
        
        
            mysql
            mysql-connector-java
            5.1.25
        
        
            org.mybatis
            mybatis
            3.4.6
        
    

    
        
            
                org.springframework.boot
                spring-boot-maven-plugin
            
            
                org.mybatis.generator
                mybatis-generator-maven-plugin
                1.3.2
                
                    ${basedir}/src/main/resources/mybatis-generator-config.xml
                    true
                    true
                
                
                    
                        org.mybatis.generator
                        mybatis-generator-core
                        1.3.2
                    
                
            
        
    

先启动eureka-server再启动eureka-client

访问http://localhost:8763/swagger-ui.html

点击可查看详情

参考资料：http://www.ruanyifeng.com/blog/2011/09/restful.html

                 《深入理解Spring+cloud与微服务构建》