整合Swagger2使用及汉化

最新推荐文章于 2021-07-21 00:03:10 发布

luzaichun

最新推荐文章于 2021-07-21 00:03:10 发布

阅读量1.6k

点赞数

分类专栏： SpringBoot 文章标签： java

本文链接：https://blog.csdn.net/qq_40911404/article/details/103652467

版权

SpringBoot 专栏收录该内容

5 篇文章 0 订阅

订阅专栏

1.引入依赖

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>

2.配置类书写

package com.netinfo.demo.config;

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;

/**
 * @author:luzaichun
 * @Date:2019/9/7
 * @Time:15:05
 **/
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //这个controller包路径记得要修改为自己controller路径
                .apis(RequestHandlerSelectors.basePackage("com.netinfo.demo.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("demo")
                .description("demo服务测试api")
                //BaseUrl,记得改为自己的（IP+port+context-path）
                .termsOfServiceUrl("http://127.0.0.1:8081/demo")
                .version("1.0")
                .build();
    }
}

3.使用swagger注解标注接口

@RestController
@RequestMapping("/user")
@Slf4j
@Api(description = "用户接口")
public class UserController {

    
    @ApiOperation(value = "获取用户信息",notes = "获取用户信息")
    //多个参数外面用@ApiImplicitParams包一层，单个参数直接用@ApiImplicitPara
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "String",paramType = "query"),
            @ApiImplicitParam(name = "password",value = "密码",required = true,dataType = "String",paramType = "query")
    })
    @PostMapping("")
    public String getUser(@RequestParam("userName") String userName, @RequestParam("password") String password) {
        log.info("入参username={},password={}",userName,password);
        //具体业务逻辑省略。。。。。

        return userName+":"+password;
    }
}

4.查看接口文档

启动我们的web工程，访问http://127.0.0.1:8081/demo/swagger-ui.html，就可以看到文档页面了。（记得url [127.0.0.1:8081/demo] 修改为你自己的base url）
在这里插入图片描述

5.测试接口

在这里插入图片描述

还有一种标记参数的写法，给大家介绍下。通过@ApiParam修饰

    @ApiOperation(value = "获取用户信息",notes = "获取用户信息")
    @PostMapping("")
    public String getUser(@ApiParam(value = "用户名")@RequestParam("userName") String userName,
                          @ApiParam(value = "密码")@RequestParam("password") String password) {
        log.info("入参username={},password={}",userName,password);
        //具体业务逻辑省略。。。。。

        return userName+":"+password;
    }

在这里插入图片描述
这种代码量会比@ApiImplicitParams注解少，但是我个人不是很喜欢。我觉得，swagger只是一种辅助，修饰类注解，不应该将它写到我的方法入参里。这里看个人喜欢了。

入参是一个VO对象的使用方式

    @PostMapping("/user2")
    @ApiOperation(value = "获取用户信息2",notes = "测试接收对象时候swagger使用方式")
    public UserVo getUser2(@RequestBody UserVo userVo){
        return userVo;
    }

UserVo标注。（此处记住，不要使用lombok的@Builder注解标注VO对象）

@Data
public class UserVo {
    @ApiModelProperty(value = "用户名",required = true,example = "zhangsan")
    private String name;
    @ApiModelProperty(value = "密码",required = true,example = "123123")
    private String password;
    //隐藏该属性
    @ApiModelProperty(hidden = true)
    private Integer age;
}

swagger-ui页面
在这里插入图片描述

最后讲一下swagger-ui汉化

1.在resources目录下创建文件夹META-INF.resources，然后在文件夹里创建一个空的，名称为swagger-ui.html的文件
2.将下面代码原封不动的拷贝到swagger-ui.html里。（拷前删空这个html里内容）

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
    <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

    <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

    <!--国际化操作：选择中文版 -->
    <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>

</head>

<body class="swagger-section">
<div id='header'>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://swagger.io">![](webjars/springfox-swagger-ui/images/logo_small.png)<span class="logo__title">swagger</span></a>
        <form id='api_selector'>
            <div class='input'>
                <select id="select_baseUrl" name="select_baseUrl"></select>
            </div>
            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
            <div id='auth_container'></div>
            <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
        </form>
    </div>
</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>

3.重启项目查看效果（如果没有汉化成功，请重新编译项目，清空浏览器缓存重试。）
在这里插入图片描述
最后推荐一篇博客，我觉得对于swagger注解讲解的很详细的一篇
https://www.cnblogs.com/JealousGirl/p/swagger2.html

luzaichun

关注

0
点赞
踩
10

收藏

觉得还不错? 一键收藏
0
评论
整合Swagger2使用及汉化

1.引入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> &l...
复制链接

扫一扫