Spring Boot整合swagger2

在整合之前先介绍一下什么是swagger、它对应的一些注解的主要以及如何设计RESTful风格接口。

Swagger由来

• 随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

• 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

 

什么是swagger2

简单点说，swagger就是一款让你更好的书写API文档的框架。

 

简介

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

 

手写Api文档的痛点：

1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。

1. 接口返回结果不明确

1. 不能直接在线测试接口，通常需要使用工具，比如postman

1. 接口文档太多，不好管理

 

同类技术

• Confluence https://www.atlassian.com/software/confluence

• README.md https://www.npmjs.com/package/readme-md

• Swagger https://swagger.io/irc/ (swagger官网)

 

常用注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息等等。

• @Api：修饰整个类，描述controller的作用

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

• @ApiParam：单个参数描述

• @ApiModel：用对象接受参数

• @ApiProperty：用对象接受参数时，描述对象的一个字段

• @ApiResponse：HTTP响应其中1个描述

• @ApiResponses：HTTP响应整体描述

• @ApiIgnore：只用该注解忽略这个API

• @ApiError：发生错误返回的信息

• @ApiImplictParam:：一个请求参数

• @ApiImplictParam：多个请求参数

@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：抛出异常的类


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

RESTful风格接口

URL定位资源，用HTTP动词（GET、POST、DELETE、DETC）描述操作。

识别（indentify）、表示（represent）、交互（interact with）。

• 看Url就知道要干什么

• 看http method就知道要干什么

• 看http status code就知道结果发生了什么

 

1.REST描述的是在网路中client和server的一种交互方式；RSET本身不实用，实用的是如何设计RESTful API（RESTful风格的网络接口)；

2. Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心。比如：

http://api.qc.com/v1/newsfeed: 获取某人的新鲜;

http://api.qc.com/v1/friends: 获取某人的好友列表;

http://api.qc.com/v1/profile: 获取某人的详细信息;

3. 用HTTP协议里的动词来实现资源的添加，修改，删除等操作。即通过HTTP动词来实现资源的状态扭转：

GET 用来获取资源，

POST 用来新建资源（也可以用于更新资源），

PUT 用来更新资源，

DELETE 用来删除资源。比如：

DELETE http://api.qc.com/v1/friends: 删除某人的好友 （在http parameter指定好友id）

POST http://api.qc.com/v1/friends: 添加好友

UPDATE http://api.qc.com/v1/profile: 更新个人资料

4. Server和Client之间传递某资源的一个表现形式，比如用JSON，XML传输文本，或者用JPG，WebP传输图片等。当然还可以压缩HTTP传输时的数据（on-wire data compression）。

5. 用 HTTP Status Code传递Server的状态信息。比如最常用的 200 表示成功，500 表示Server内部错误等。

 

1.REST很好地利用了HTTP本身就有的一些特征，如HTTP动词、HTTP状态码、HTTP报头等等。

• HTTP动词

GET     获取一个资源 
POST    添加一个资源 
PUT     修改一个资源 
DELETE  删除一个资源 

• HTTP状态码

200 OK 
400 Bad Request 
500 Internal Server Error

• HTTP报头

Authorization 认证报头 
Cache-Control 缓存报头 
Cnotent-Type  消息体类型报头 
......

怎么用RESTful

1、每个资源使用2个URL，网址中只能有名词

2、对于资源的操作类型由HTTP动词来表示

3、统一的返回结果

4、返回正确的状态码

5、允许通过HTTP内容协商，建议格式预定义为JSON

6、对可选发杂的参数，使用查询字符串（？）

7、返回有用的错误信息(message)

8、非资源请求用动词，这看起似乎和1中的说法有矛盾，但这里指的是非资源，而不是资源

 

接下来使用Spring Boot整个Swagger2直接生成接口文档的方法，开始！（默认Maven方式）

一、pom.xml导入依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--swagger-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!--mysql驱动-->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
</dependency>
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

二、Swagger配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {


    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.jacklin.springbootswagger"))
                .paths(PathSelectors.any())
                .build();
    }
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("Spring Boot利用Swagger构建RESTful APIs文档")
                .description("简单的restful风格")
                .termsOfServiceUrl("https://mp.csdn.net/")
                .version("1.0")
                .build();


    }

 

三、Entity

/**
 * @Author:JackLin
 * @Create 2019/3/24 14:23
 */
@Data
@Entity
public class User {


    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;


    private String username;


    private String password;


    private String email;

四、repository

这里的接口继承CurdRepository，当然你也可以选择其他接口。

/**
 * @Author:JackLin
 * @Create 2019/3/24 15:01
 */
public interface UserRepository extends CrudRepository<User,Long> {


}

五、service

/**
 * @Author:JackLin
 * @Create 2019/3/24 15:09
 */
public interface UserService  {


    /**
     * 添加用户
     */
    public void save(User user);


    /**
     * 根据id删除用户
     * @param id
     */
    public void delUserById(Long id);


    /**
     * 根据id查询所有用户
     * @return
     */
    public Optional<User> selcetUserById(Long id);

六、ServiceImpl

/**
 * @Author:JackLin
 * @Create 2019/3/24 15:10
 */
@Service
public class UserServiceImpl implements UserService {


    @Autowired
    private UserRepository userRepository;


    @Override
    public void  save(User user) {
        this.userRepository.save(user);
    }


    @Override
    public void delUserById(Long id) {
        this.userRepository.deleteById(id);
    }


    @Override
    public Optional<User> selcetUserById(Long id) {
        Optional<User> user = this.userRepository.findById(id);
        return user;
    

七、controller

@RestController
@RequestMapping("/user")
@Api(value = "UserController",description = "提供RESTful风格的用户的CRUD服务")
public class UserController {


    @Autowired
    private UserService userService;


    /**
     * 添加用户
     */
    @PostMapping
    @ApiOperation("添加用户")
    public void  add(User user){
         User user1 = new User();
         user1.setUsername("晓明");
         this.userService.save(user1);
    }


    /**
     *根据id删除用户
     * @param id
     * @return
     */
    @DeleteMapping("/{id}")
    @ApiOperation("通过Id删除用户")
    public void  delete(@PathVariable Long id) {
        this.userService.delUserById(id);
    }


    /**
     * 根据id查询用户
     * @param id
     * @return
     */
    @GetMapping("/{id}")
    @ApiOperation("根据Id查询用户")
    public Optional<User> findUserById(Long id){
        return this.userService.selcetUserById(id);
    

 

最后运行项目，运行成功后，访问：http://localhost:8080/swagger-ui.html，便可以看到我们刚才构建的API文档了。