springboot利用swagger2.0构建api文档

样例：

1. pom.xml添加依赖

		
			io.springfox
			springfox-swagger2
			2.7.0
		

		
		
			io.springfox
			springfox-swagger-ui
			2.6.1
		

2. 创建类Swagger2
   与启动类Application同级
   

package com.rmw.crawler.manage;

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;

/**

 * @Description:    springboot利用swagger构建api文档

 * @Author:         psw

 * @CreateDate:     2018/9/17 14:49

 * @UpdateUser:     psw

 * @UpdateDate:     2018/9/17 14:49

 * @UpdateRemark:   修改内容

 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //"com.rmw.crawler.manage.controller"， web层所在的目录
                .apis(RequestHandlerSelectors.basePackage("com.rmw.crawler.manage.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档---数据源管理系统")
                .description("简单优雅的restfun风格")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

3. web中的controller中的方法上添加注解 如下图：
   

 常用注解：
- @Api()用于类；
表示标识这个类是swagger的资源
- @ApiOperation()用于方法；
表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明：
@Api()
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代 

代码：

package com.rmw.crawler.manage.controller;

import com.alibaba.dubbo.config.annotation.Reference;
import com.rmw.crawler.manage.bean.DataSource;
import com.rmw.crawler.manage.service.SourceService;


import com.rmw.dubbo.api.CrawlerSourceInterface;
import com.rmw.dubbo.entity.*;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.BindingResult;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * @Description:    source数据源相关操作
 * @Author:         psw
 * @CreateDate:     2018/9/20 17:39
 * @UpdateUser:     psw
 * @UpdateDate:     2018/9/20 17:39
 * @UpdateRemark:   修改内容
 */
@RestController
@RequestMapping("/source")
public class SourceController {

    public static Logger log = LoggerFactory.getLogger(SourceController.class);

    //@Reference(version = "1.0.0")
    @Autowired
    private CrawlerSourceInterface sourceService;


    /**
     *  http://localhost:8080/crawler-manage/swagger-ui.html#/
     * 功能描述: 获取数据源列表信息(无分页)
     * @auther: psw
     * @param:
     * @return:
     * @exception
     * @date: 2018/9/17 16:35
     */

    @ApiOperation(value="获取数据源列表信息", notes="获取数据源列表")
    @RequestMapping(value = "/find/all",method= RequestMethod.GET)

    public List find(SourceVo sourceVo){
        List sourceList = sourceService.findAll(sourceVo);
        log.info("获取数据源列表信息结果：{}",sourceList);
        return sourceList;
    }

    /**
     * 无参数
     * @return
     */
    @RequestMapping(value = "/find/list",method= RequestMethod.GET)
    public List finds(){
        List sourceList = sourceService.findList();
        log.info("获取数据源列表信息结果：{}",sourceList);
        return sourceList;
    }

   /**
    *
    * 功能描述: 根据sourceId来获取数据源详细信息
    * @auther: psw
    * @param:
    * @return:
    * @exception
    * @date: 2018/9/17 16:36
    */
    @ApiOperation(value="根据sourceId获取数据源详细信息", notes="根据sourceId来获取数据源详细信息")
    @ApiImplicitParam(name = "sourceId", value = "数据源ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "/get/{sourceId}",method= RequestMethod.GET)
    public Result findBySourceId(@PathVariable Integer sourceId){
        log.info("根据sourceId来获取数据源详细信息,sourceId：{}",sourceId);
        CrawlerSource dataSource = sourceService.getSource(sourceId);
        log.info("sourceId:{},数据源详细信息:{}",sourceId,dataSource);
        return Result.success(dataSource);
    }

    /**
     * 根据条件分页查询数据源
     * @param sourceVo
     * @param pageNo
     * @param pageSize
     * @return
     */
    @ApiOperation(value="根据条件分页查询", notes="根据条件分页查询获取数据源详细信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNo", value = "页码", required = true, dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "pageSize", value = "每页数量", required = true, dataType = "int", paramType = "query"),
            @ApiImplicitParam(name = "sourceVo", value = "查询参数", required = false, dataType = "SourceVo")
    })
    @RequestMapping(value = "/get/page",method= RequestMethod.GET)
    public Result findBySourceVo(SourceVo sourceVo, int pageNo, int pageSize){
        log.info("根据条件分页查询，查询参数：{}", sourceVo);
        PageModel sourcePageModel = sourceService.findPagerByCondition(sourceVo,pageNo, pageSize);
        log.info("根据条件分页查询，查询结果：{}", sourcePageModel);
        return Result.success(sourcePageModel);
    }

    /**
     * 新增数据源
     * @param dataSource
     * @return
     */
    @ApiOperation(value="新增数据源", notes="新增数据源")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "dataSource", value = "新增数据源", required = true, dataType = "CrawlerSource")
    })
    @RequestMapping(value = "/save",method= RequestMethod.POST)
    public Result saveSource(@RequestBody @Validated CrawlerSource dataSource, BindingResult bindingResult){
        if (bindingResult.hasErrors()) {
            return Result.error(Code.INVALID_PARAMETER);
        }
        log.info("新增数据源:{}",dataSource);
        Result data = sourceService.insert(dataSource);
        return data;
    }


    /**
     * 更新数据源
     * @param dataSource
     * @return
     */
    @ApiOperation(value="编辑数据源", notes="编辑数据源")
    @RequestMapping(value = "/update",method= RequestMethod.POST)
    public Result updateSource(@RequestBody CrawlerSource dataSource){
        log.info("更新数据源:{}",dataSource);
        sourceService.update(dataSource);
        return Result.success(Code.OK);
    }

    /**
     * 删除数据源
     * @param dataSource
     * @return
     */
    @ApiOperation(value="删除数据源", notes="删除数据源")
    @RequestMapping(value = "/delete",method= RequestMethod.POST)
    public Result deleteSource(@RequestBody CrawlerSource dataSource){
        log.info("删除数据源:{}",dataSource);
        sourceService.deleteSource(dataSource);
        return Result.success(Code.OK);
    }

    /**
     * 开启关闭
     * @param dataSource
     * @return
     */
    @ApiOperation(value="开启/关闭数据源", notes="开启/关闭数据源")
    @RequestMapping(value = "/switch",method= RequestMethod.POST)
    public Result startOrStop(@RequestBody CrawlerSource dataSource){
        log.info("开启/关闭数据源:{}",dataSource);
        sourceService.startOrStop(dataSource);
        return Result.success(Code.OK);
    }



}

4. 启动项目：
   进入接口文档页面，文章开头的那个
   http://localhost:8089/crawler-manage/swagger-ui.html#/