SpringBoot整合Swigger2

1.引入所需要的依赖

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

2.编写配置类

package com.swagger.demo.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;

import java.awt.*;

/**
 * 基础的配置是对整个API文档的描述以及一些全局性的配置，对所有接口起作用。这里涉及到两个注解：
 *
 * 　　@Configuration是表示这是一个配置类，是JDK自带的注解，前面的文章中也已做过说明。
 *
 * 　　@EnableSwagger2的作用是启用Swagger2相关功能。
 *
 * 　　在这个配置类里面我么实例化了一个Docket对象，这个对象主要包括三个方面的信息：
 *
 * 　　　　（1）整个API的描述信息，即ApiInfo对象包括的信息，这部分信息会在页面上展示。
 *
 * 　　　　（2）指定生成API文档的包名。
 *
 * 　　　　（3）指定生成API的路径。按路径生成API可支持四种模式，这个可以参考其源码：
 */
@Configuration  //配置类
@EnableSwagger2  //开启swagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.swagger.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("破天系统Restful API")
                .description("破天系统Restful API")
                .termsOfServiceUrl("http://www.bejson.com/")
                .version("1.0")
                .build();
    }
}

3.controller层的接口编写

package com.swagger.demo.controller;


import com.swagger.demo.pojo.Article;
import com.swagger.demo.pojo.WebResponse;
import com.swagger.demo.service.ArticleService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import static org.springframework.web.bind.annotation.RequestMethod.*;

/**
 * @ApiOperation，整个接口属性配置：
 *
 * 　　　　value：接口说明，展示在接口列表。
 *
 * 　　　　notes：接口详细说明，展示在接口的详情页。
 *
 * 　　　　tags：接口的标签，相同标签的接口会在一个标签页下展示。
 *
 * 　　　　httpMethod：支持的HTTP的方法。
 *
 * 　　@ApiImplicitParams，@ApiImplicitParam的容器，可包含多个@ApiImplicitParam注解
 *
 * 　　@ApiImplicitParam，请求参数属性配置：
 *
 * 　　　　name：参数名称
 *
 * 　　　　value：参数说明
 *
 * 　　　　required：是否必须
 *
 * 　　　　dataType：数据类型　　
 *
 * 　　@ApiResponses，@ApiResponse容器，可以包含多个@ApiResponse注解
 *
 * 　　@ApiResponse，返回结果属性配置：
 *
 * 　　　　code：返回结果的编码。
 *
 * 　　　　message：返回结果的说明。
 *
 * 　　　　response：返回结果对应的类。　　　
 */
@RestController
@RequestMapping("/rest")
public class ArticleRestController {
  @Autowired
  private ArticleService articleService;
  @RequestMapping(value = "/article", method = POST, produces = "application/json")
  @ApiOperation(value = "添加文章", notes = "添加新的文章", tags = "Article",httpMethod = "POST")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "title", value = "文章标题", required = true, dataType = "String"),
      @ApiImplicitParam(name = "summary", value = "文章摘要", required = true, dataType = "String"),
      @ApiImplicitParam(name = "status", value = "发布状态", required = true, dataType = "Integer")
  })
  @ApiResponses({
      @ApiResponse(code=200,message="成功",response= WebResponse.class),
  })
  public WebResponse<Map<String,Object>> saveArticle(@RequestBody Article article){
    articleService.saveArticle(article);
    HashMap<Object, Object> ret = new HashMap<>();
    ret.put("id",article.getId());
    WebResponse<Map<String,Object>> response = WebResponse.getSuccessResponse(ret);
    return response;
  }
  @ApiOperation(value = "删除文章", notes = "根据ID删除文章", tags = "Article",httpMethod = "DELETE")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "文章ID", required = true, dataType = "Long")
  })
  @RequestMapping(value = "/{id}",method = DELETE,produces = "application/json")
  public WebResponse<?> deleteArticle(@PathVariable Long id){
    Article article = articleService.getById(id);
    article.setStatus(-1);
    articleService.saveArticle(article);
    return WebResponse.getSuccessResponse(new HashMap<>());
  }
  @ApiOperation(value = "获取文章列表", notes = "可以根据标题进行模糊查询", tags = "Article",httpMethod = "GET")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "title", value = "文章标题", required = false, dataType = "String"),
      @ApiImplicitParam(name = "pageSize", value = "每页文章数量", required = false, dataType = "Integer"),
      @ApiImplicitParam(name = "pageNum", value = "分页的页码", required = false, dataType = "Integer")
  })
  @RequestMapping(value = "/article/list", method = GET, produces = "application/json")
  public WebResponse<?> listArticles(String title, Integer pageSize, Integer pageNum) {
    if (pageSize == null) {
      pageSize = 10;
    }
    if (pageNum == null) {
      pageNum = 1;
    }
    int offset = (pageNum - 1) * pageSize;
    List<Article> articles = articleService.getArticles(title, 1L, offset, pageSize);
    return WebResponse.getSuccessResponse(articles);
  }
  @ApiOperation(value = "更新文章", notes = "更新文章内容", tags = "Article",httpMethod = "PUT")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "文章ID", required = true, dataType = "Long"),
      @ApiImplicitParam(name = "title", value = "文章标题", required = false, dataType = "String"),
      @ApiImplicitParam(name = "summary", value = "文章摘要", required = false, dataType = "String"),
      @ApiImplicitParam(name = "status", value = "发布状态", required = false, dataType = "Integer")
  })
  @RequestMapping(value = "/article/{id}", method = PUT, produces = "application/json")
  public WebResponse<?> updateArticle(@PathVariable Long id,@RequestBody Article article){
    article.setId(id);
    articleService.updateArticle(article);
    return WebResponse.getSuccessResponse(new HashMap<>());
  }
}

4、启动SpringBoot项目，访问 http://localhost:端口/swagger-ui.html

 

5、Swagger注解

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

    @Api：修饰整个类，描述Controller的作用
    @ApiOperation：描述一个类的一个方法，或者说一个接口
    @ApiParam：单个参数描述
    @ApiModel：用对象来接收参数
    @ApiProperty：用对象接收参数时，描述对象的一个字段
    @ApiResponse：HTTP响应其中1个描述
    @ApiResponses：HTTP响应整体描述
    @ApiIgnore：使用该注解忽略这个API
    @ApiError ：发生错误返回的信息
    @ApiImplicitParam：一个请求参数
    @ApiImplicitParams：多个请求参数