样例:
- pom.xml添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- 接口API生成html文档 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
- 创建类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();
}
}
- 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<CrawlerSource> find(SourceVo sourceVo){
List<CrawlerSource> sourceList = sourceService.findAll(sourceVo);
log.info("获取数据源列表信息结果:{}",sourceList);
return sourceList;
}
/**
* 无参数
* @return
*/
@RequestMapping(value = "/find/list",method= RequestMethod.GET)
public List<CrawlerSource> finds(){
List<CrawlerSource> 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<CrawlerSource> 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);
}
}
- 启动项目:
进入接口文档页面,文章开头的那个
http://localhost:8089/crawler-manage/swagger-ui.html#/