SpringBoot集成Swagger2 以及汉化 快速教程

(一) Swagger介绍

               Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件

(二)为什么使用Swagger

                在现在的开发过程中还有很大一部分公司都是以口口相传的方式来进行前后端的联调，而接口文档很大一部分都只停留在了说说而已的地步，很大一部分的原因就是”懒”，不想写啊，写了代码再写文档，反正我是懒，只要不是强制性要求，没人会愿意写这东西，而且在写的过程中，一个字母的错误就会导致联调时候的很大麻烦，但是通过Swagger，我们可以省略了这一步，而且文档出错率近乎于零，只要你在写代码的时候，稍加几个注解，文档自动生成。还有一点就是文档的修改，定义好的接口并不是一成不变的，可能在开发过程中文档修改不止一次的变化，这个时候就会很难受了，通过Swagger，在线自动生成你怎么写他怎么生，方不方便你自己赶脚

(三)SpringBoot集成Swagger

       1) 添加依赖

<!--Swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
 <!--Swagger-UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

     2) 创建配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.result.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger2构建api文档")
                .description("Swagger的RESTful风格API")
                .termsOfServiceUrl("https://www.baidu.com")
                .version("1.0")
                .build();
    }

}

 

这些做好之后就已经集成了swagger-ui.html 

我们访问

http://localhost:8080/swagger-ui.html

 

 

 

这样其实我们已经配好了,但是怎么使用呢,其实我们只用几个注解就能搞定

 

@Api()用于类；
表示标识这个类是swagger的资源

@ApiOperation()用于方法；
表示一个http请求的操作

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

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

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

@ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法
表示单独的请求参数

 

例:

@RestController
@Api(value="用户controller",tags={"用户操作接口"})
public class UserController {


    @PostMapping("/login")
    @ApiOperation(value = "登录", notes = "账号密码必输")
    public ResponseResult login(String username,String password){
        if ("admin".equals(username) || "123456".equals(password)){
            User user = new User();
            user.setUsername(username);
            user.setPassword(password);
            user.setCity("中国");
            user.setSex("男");
            return new ResponseResult().setData(user);
        }else {
            return new ResponseResult("000000");
        }
    }

}

启动之后:

 

 

(四)Swagger-UI的汉化

  对于上面我们所用的版 2.7.0，里面是含有国际化的(2.7.0以上版本不含国际化包)

  

 

   国际化的实现

             1) 在你的sources创建  META-INF/resources    ，在这个目录下创建swagger-ui.html

             2) 找到你导入的springfox-swagger-ui  的包，找到这个html文件把里面的内容copy到你新建的swagger-ui.html

     

 

          3) 加入国际化的js

    <!-- 加入国际化的js -->
    <script src="webjars/springfox-swagger-ui/lang/translator.js" type="text/javascript"></script>
    <script src="webjars/springfox-swagger-ui/lang/zh-cn.js" type="text/javascript"></script>

 

重启项目  汉化成功

 

 

对于swagger2.7.2以后的版本没有包含国际化的内容，上述的方式是不行的，目前我还没有找到对于新版本国际化的方案

 

如果谁有新版本国际化的方案请留言，谢谢