1. 简介

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

2. 添加Swagger2依赖

注意：

只添加下面两个依赖的前提是SpringMVC的项目能够正常运行

         
     
      io.springfox
          
     
      springfox-swagger2
          
     
      2.6.1
     
    
    
         
     
      io.springfox
          
     
      springfox-swagger-ui
          
     
      2.6.1
     
    

3. 创建Swagger2配置类

3.1 自定义配置类

//启用Swagger2@EnableSwagger2        public class Swagger2Config extends WebMvcConfigurationSupport {       @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo()).select()                //扫描指定包中的swagger注解                //.apis(RequestHandlerSelectors.basePackage("com.xia.controller"))                //扫描所有有注解的api，用这种方式更灵活                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                .paths(PathSelectors.any())                .build();    }    @Bean    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("基础平台 RESTful APIs")                .description("基础平台 RESTful 风格的接口文档，内容详细，极大的减少了前后端的沟通成本，同时确保代码与文档保持高度一致，极大的减少维护文档的时间。")                .termsOfServiceUrl("http://xiachengwei5.coding.me")                .version("1.0.0")                .termsOfServiceUrl("http://xxx.xxx.com")                .license("LICENSE")                .licenseUrl("http://xxx.xxx.com")                .build();    }        @Override    public void addResourceHandlers(ResourceHandlerRegistry registry) {        registry.addResourceHandler("swagger-ui.html")                .addResourceLocations("classpath:/META-INF/resources/");        registry.addResourceHandler("/webjars/**")                .addResourceLocations("classpath:/META-INF/resources/webjars/");    }    }

3.2 使用xml中配置

4. 初步展示效果

5. 编写常用Swagger注解

添加Swagger注解，能够让Swagger的APi文档页面更加友好，更加方便理解和调试

5.1 实体注解

• @ApiModel() 用于类,表示对类进行说明，用于参数用实体类接收

  • value–表示对象名
  • description–描述

• @ApiModelProperty() 用于方法，字段；表示对model属性的说明或者数据操作更改

  • value:字段说明
  • name:重写属性名字
  • dataType:重写属性类型
  • required:是否必填
  • example:举例说明
  • hidden:隐藏

用法如下代码所示：

@ApiModel(value = "UserInfo:用户信息")public class UserInfo implements Serializable {    @ApiModelProperty(value = "ID")    private Integer id;    @ApiModelProperty(value = "登录账号", required = true)    private String userNo;    @ApiModelProperty(value = "姓名", required = true)    private String userName;}

显示效果如下所示：

5.2 控制类注解

下面的这些注解都放在Controller控制器类上面

5.2.1 @Api

修饰整个类，描述Controller的作用

@Api(tags = {"用户操作接口"})@RestController@RequestMapping(value = "/userInfo")public class UserInfoController {}

• tags：控制类功能说明，tags是一个字符串数组，可以添加多个标签

tags = {"用户操作接口","对用户的一些增删改查操作"}

效果如下：

• value:也是说明，可以使用tags替代

5.2.2 @ApiOperation

描述一个类的一个方法，或者说一个接口

@GetMapping(value = "/selectOne")    @ApiOperation(value = "value作用：查询单个人员信息", notes = "notes作用：输入用户ID",tags = {"查询"})    public ZingResult selectOne() {        return ZingResult.success();    }    @GetMapping(value = "/update")    @ApiOperation(value = "value作用：更新用户信息", notes = "notes作用：输入用户各项参数",tags = {"更新"})    public ZingResult update() {        return ZingResult.success();    }

• value用于方法描述
• notes用于提示内容

• tags可以重新分组

5.2.3 @ApiParam

单个参数描述

• name–参数名
• value–参数说明
• required–是否必填

@GetMapping(value = "/selectOne")    @ApiOperation(value = "value作用：查询所有的人员信息并分页展示", notes = "notes作用：输入page和size来分页查询", tags = {"查询"})    public ZingResult selectOne(@ApiParam(name="page",value="页码",required=true) Integer page,@ApiParam(name="size",value="数量",required=true) Integer size) {        return ZingResult.success();    }

5.2.4 @ApiImplicitParams()和@ApiImplicitParam

用于方法，包含多个@AplimplicitParam

• name–参数ming
• value–参数说明
• dataType–数据类型
• paramType–参数类型
• example–举例说明

@ApiImplicitParams({        @ApiImplicitParam(name = "page", value = "跳转到的页数", required = true, paramType = "query"),        @ApiImplicitParam(name = "size", value = "每页展示的记录数", required = true, paramType = "query")})public ZingResult selectAllUsers(Integer page, Integer size) {    return ZingResult.success();}

效果如下图所示：

5.2.5 @ApiIgnore()

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

比较简单, 这里不做举例

6. 加载配置文件

加载配置文件中的内容，灵活配置swagger APIinfo的信息

注意Spring的@Value读取配置文件中的中文会乱码

6.1 配置文件

#Swagger开关SWAGGER.ENABLE = true#Swagger API配置SWAGGER.TITLE = 基础平台 RESTful APIsSWAGGER.DESC = 基础平台 RESTful 风格的接口文档，内容详细，极大的减少了前后端的沟通成本，同时确保代码与文档保持高度一致，极大的减少维护文档的时间。

6.2 加载配置文件，并制定utf-8编码

• 使用PropertyPlaceholderConfigurer加载

    
        
             
                  
       
        classpath:dubbo-server.properties
                   
       
        classpath:server.properties
               
          
         
     
    

• 使用context:property-placeholder 加载

• 使用注解加载

@PropertySource(value = "classpath:conf/copyWriteUI.properties",encoding = "utf-8")