spring集成swagger-在线发布预览rest API（入门集成）

1、关于swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
采用后端API通过注解形势，自动生成的文档，解放接口文档书写和订正，可以大幅提高开发效率，供前端开发人员查看后端WEB API的文档来进行开发。

** 说明** ：此文是针对spring项目进行集成，并非springboot项目，进行文件配置，请注意，springboot请参考其他教程

开始集成

1、准备jar包下载，pom文件中引入以下jar文件，普通工程自行下载该jar包，并进行引入

		<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>

1. 注意 ：版本需选择2.7后高版本，否则会@Api(tags={中文})无法点击展开
2. swagger 配置文件类，通过注解来启用swagger，并配置扫描包

/**
* Swagger配置
* @since 2020-04-16
*/
@EnableWebMvc
@EnableSwagger2
@Configuration
public class SwaggerConfig {

   @Bean
   public Docket createRestApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("mmc.web.noc")) // 注意修改此处的包名，扫描该包下的注解
               .paths(PathSelectors.any())
               .build();
   }

   private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("接口列表 v1.1.0") // 任意，请稍微规范点
               .description("接口测试") // 任意，请稍微规范点
               .termsOfServiceUrl("http://127.0.0.1:8081/mmc-web/swagger-ui.html") // 换成自己的ip:port/工程名/swagger-ui.html
               .version("1.1.0")
               .build();
   }
}

ps 需要注意的是，如果系统配置了功能拦截或过滤器，上面配置的访问路径需要在自己工程中放开过滤，否则需要登陆后才能访问，根据自己工程，进行免过滤配置。
另外需要注意的是，如果配置 了spring包自动扫描，需要将该类放入到扫描包内，否则会不生效
以下是shiro放开过滤：

/swagger-ui.html = anon
/swagger*/** = anon
/v2/** = anon
/webjars/** = anon

3. 将swagger-ui从jar包中，添加入资源中，直接复制使用，不需修改

<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

4. 配置Controller类

/**
 * 项目管理
 * @author 
 */
@Controller
@RequestMapping("nocProject")
@Api(value="项目管理API",tags={"项目管理"})
public class NocProjectController {
	
	@Resource
	private NocProjectService nocProjectService;
	
	
	@ApiOperation(value = "添加项目")
	@RequestMapping(method=RequestMethod.POST,value="/save1")
	@ResponseBody
	private ResponseContext Demo(@ModelAttribute NocTestModel test){
		ResponseContext rc = new ResponseContext();
		rc.setResponseData(test);
		return rc;
	}
	
	@ApiOperation(value = "添加项目2")
	@RequestMapping(method=RequestMethod.POST,value="/save2")
	@ResponseBody
	private ResponseContext Demo2(@RequestBody NocTestModel test){
		ResponseContext rc = new ResponseContext();
		rc.setResponseData(test);
		return rc;
	}
	
	@ApiOperation(value = "查询项目",notes = "查询项目")
    @RequestMapping(value = {"/save"}, method = {RequestMethod.POST})
    @ResponseBody
    public ResponseContext save(@ApiParam("商品名称") 
    				@RequestParam(value="goodsName",required=true) 
    				String goodsName) {
		ResponseContext rc = new ResponseContext();
		rc.setResponseData(goodsName);
    	return rc;
    }
}

具体使用举例说明：
在swagger-annotations jar包中 1.5.X版本以上, 注解io.swagger.annotations.API中的description被废弃了。新的swagger组件中使用了新的方法来对Web api 进行分组。原来使用 description ，默认一个Controller类中包含的方法构成一 个api分组。现在使用tag，可以更加方便的分组。比如把两个Controller类里的方法划分成同一个分组。tag的key用来区分不同的分组。tag的value用做分组的描述。
@ApiOperation 中value是api的简要说明，在界面api 链接的右侧，少于120个字符。
@ApiOperation 中notes是api的详细说明，需要点开api 链接才能看到。
@ApiOperation 中 produces 用来标记api返回值的具体类型。这里是json格式，utf8编码。

该类列举了单个多个参数传递，通过@ApiParam() 进行描述，也进行了对象传参示例，通过@RequestBody和@ModelAttribute进行控制，以下为说明和区别。
在此说明 ：此处未对参数如Map、JsonObject等对象引用说明，也未进行尝试。

@RequestBody
用于接收json串 如ajax请求的data参数 可在直接接收转换到Pojo

@ModelAttribute
用于直接接受url?后面的参数 如url?id=123&name=456 可在直接接收转换到Pojo

@Api()
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list，由于版本更新，description已经过时，通过tags进行代替

@ApiOperation() 用于方法；表示一个http请求的操作
value用于方法描述
notes用于提示内容
tags可以重新分组（视情况而用）

@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填

5.Model实体类

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "视频类型")
public class NocTestModel {

	@ApiModelProperty(value = "类型名称")
    private String title;

    public String getTitle() {
		return title;
	}

	public void setTitle(String title) {
		this.title = title;
	}

	public Integer getSortOrder() {
		return sortOrder;
	}

	public void setSortOrder(Integer sortOrder) {
		this.sortOrder = sortOrder;
	}

	public Integer getStatus() {
		return status;
	}

	public void setStatus(Integer status) {
		this.status = status;
	}

	@ApiModelProperty(value = "排序值")
    private Integer sortOrder;

    @ApiModelProperty(value = "是否启用 0启用 -1禁用")
    private Integer status = 0;
}

具体使用举例说明：
实体类必须具备get\set方法，或者使用了Lombok进行动态生成。否则前台展示会无法传入参数。

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上

未做尝试，后续更新
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
name–参数ming
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明

至此，我们已经完成了集成

输入地址访问：http://ip:port/工程名/swagger-ui.html

总结

1. 引入jar文件
2. 创建SwaggerConfig配置类，使用注解，开始Swagger功能（注意：在spring自动扫描包下）
3. 将jar包文件ui资源，加入到mvc:resources中。
4. 配置免过滤拦截器
5. Controller 引入@API等注解，进行描述

如有不正之处，请见谅！