SpringBoot集成Swagger的详细步骤

谁借莪１个温暖的怀抱￠ 2023-02-11 13:29 50阅读 0赞

目录  
一、简介以及使用

二、整合步骤

三、注解说明

一、简介以及使用  
号称：世界最流行的API框架

官网：http://swagger.io/

解决什么问题：

在前后台分离的开发模式中，减小接口定义沟通成本，方便开发过程中测试，自动生成接口文档

使用方式：

1、通过官网配置文档，一个接口一个接口编写

2、通多注解配置，动态生成json数据，由框架自动生成代码展示

二、整合步骤  
项目框架要求：本文以springboot

1、在pom文件中引入swagger支持的相关依赖---即jar包

<dependencies>
            <dependency> 
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.7.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.7.0</version>
            </dependency>
            <dependency> 
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-devtools</artifactId>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-test</artifactId>
                <scope>test</scope>
            </dependency>
        </dependencies>

2、添加配置---即编写swagger启动类SwaggerConfig.java

package dcc.core;
     
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.EnableWebMvc;
     
    import springfox.documentation.builders.ApiInfoBuilder;
    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;
     
    @Configuration //声明该类为配置类
    @EnableSwagger2 //声明启动Swagger2
     
    public class SwaggerConfig{
        @Bean
        public Docket customDocket() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.epoch.ccfindcars.controller"))//扫描的包路径
                    .build();
        }
     
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("反向寻车")//文档说明
                    .version("1.0.0")//文档版本说明
                    .build();
        }
    }

3、编写接口文档----即开启spring整合swagger配置

Swagger2 基本使用：

@Api 描述类/接口的主要用途  
@ApiOperation 描述方法用途  
@ApiImplicitParam 描述方法的参数  
@ApiImplicitParams 描述方法的参数(Multi-Params)  
@ApiIgnore 忽略某类/方法/参数的文档  
Swagger2 使用注解来编写文档：

Swagger2编写接口文档相当简单，只需要在控制层（Controller）添加注解来描述接口信息即可。

package com.epoch.ccfindcars.controller;
     
    import com.epoch.ccfindcars.entity.LotAddress;
    import com.epoch.ccfindcars.entity.LotAddressList;
    import com.epoch.ccfindcars.service.LotAddressService;
    import com.epoch.ccfindcars.service.LotAddressServiceList;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RestController;
     
    import java.util.List;
     
    /**
     * @Author: ljj
     * @Description: 反向寻车功能
     * @Date: 
     */
    @RestController
    @Api("反向寻车管理功能")
    public class ReverseForCarController {
     
        @Autowired
        private LotAddressService lotAddressService;
     
        @Autowired
        private LotAddressServiceList lotAddressServiceList;
     
        @ApiOperation("通过id确定唯一车牌")
        @GetMapping("/getone")
        @ApiImplicitParam(name = "id",value = "车位表对应的id",dataType = "int ")
        public LotAddress getOneCatLotAddress(int id) {
            LotAddress lotAddress = lotAddressService.OneCatLotAddress(id);
            return lotAddress;
        }
     
        /**
         * 快速寻车：通过输入车牌中的一个或多个字母或数字，快速查询车位
         *
         * @param carLicense
         * @return lotAddressList
         */
        @ApiOperation("通过车牌号，获取相关车牌列表")
        @GetMapping("/serchlike")
        @ApiImplicitParam(name = "carLicense",value = "车牌号",dataType = "String")
        public List<LotAddressList> getCarLotAddress(String[] carLicense) {
     
            StringBuffer sc = new StringBuffer();
            for (int i = 0; i < carLicense.length; i++) {
                sc.append(carLicense[i]);
            }
            String s = sc.toString();
            System.out.println(s);
            List<LotAddressList> lotAddressList = lotAddressServiceList.getCatAllRow(s);
            return lotAddressList;
        }
     
        @ApiOperation("通过车位号来获取车位")
        @GetMapping("/findcar")
        @ApiImplicitParam(name = "carAddress",value = "车位号",dataType = "String")
        public List<LotAddressList> getCarAddressByCarAddress(String carAddress) {
            List<LotAddressList> carAddressByCarLicense = lotAddressService.findCarAddressByCarLicense(carAddress);
            return carAddressByCarLicense;
        }
     
    }

4查阅接口文档

编写文档完成之后，启动当前项目，在浏览器打开：  
\[ http://localhost:8080/swagger-ui.html \] --（端口根据自己设置来写）看到效果如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70][]

5测试接口

Swagger2的强大之处不仅在于快速生成整洁优雅的RestAPI文档，同时支持接口方法的测试操作（类似于客户端PostMan）。

以通过车位号获取车位为例，随便输入参数5，直接点击“试一下”按钮：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 1][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 2][]

## **6.此外，本教程还额外提供了UI汉化教程，去除阅读官方英文界面的烦恼。（目前Swagger汉化教程是找不到的，因为官方手册实在写得太烂。。）**   ①.默认的英文界面UI   想必很多小伙伴都曾经使用过Swagger，但是打开UI界面之后，却是下面这样的画风，纯英文的界面并不太友好，作为国人还是习惯中文界面。 ##

②.定制中文界面  
2.1添加首页和译文  
重点来了，在src/main/resources目录下创建META-INF\\resources目录，然后创建一个名称为"swagger-ui.html" 的HTML文件。如图：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 3][]

注意文件名不要起错，接下来将下面这段内容原封不动的拷贝进去。

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

OK 大功告成 我们访问 [http://localhost:4040/swagger-ui.html][http_localhost_4040_swagger-ui.html] 看看显示效果：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 4][]

### **2.2更详细的译文翻译（非必需）**   如果想进一步调整译文，可以在META-INF\\resources\\webjars\\springfox-swagger-ui\\lang 目录下添加zh-cn.js文件. ###

然后在译文（zh-cn.js ）根据个人喜好来添加翻译内容，如下

'use strict';
     
    /* jshint quotmark: double */
    window.SwaggerTranslator.learn({
        "Warning: Deprecated":"警告：已过时",
        "Implementation Notes":"实现备注",
        "Response Class":"响应类",
        "Status":"状态",
        "Parameters":"参数",
        "Parameter":"参数",
        "Value":"值",
        "Description":"描述",
        "Parameter Type":"参数类型",
        "Data Type":"数据类型",
        "Response Messages":"响应消息",
        "HTTP Status Code":"HTTP状态码",
        "Reason":"原因",
        "Response Model":"响应模型",
        "Request URL":"请求URL",
        "Response Body":"响应体",
        "Response Code":"响应码",
        "Response Headers":"响应头",
        "Hide Response":"隐藏响应",
        "Headers":"头",
        "Try it out!":"试一下！",
        "Show/Hide":"显示/隐藏",
        "List Operations":"显示操作",
        "Expand Operations":"展开操作",
        "Raw":"原始",
        "can't parse JSON.  Raw result":"无法解析JSON. 原始结果",
        "Example Value":"示例",
        "Click to set as parameter value":"点击设置参数",
        "Model Schema":"模型架构",
        "Model":"模型",
        "apply":"应用",
        "Username":"用户名",
        "Password":"密码",
        "Terms of service":"服务条款",
        "Created by":"创建者",
        "See more at":"查看更多：",
        "Contact the developer":"联系开发者",
        "api version":"api版本",
        "Response Content Type":"响应Content Type",
        "Parameter content type:":"参数类型:",
        "fetching resource":"正在获取资源",
        "fetching resource list":"正在获取资源列表",
        "Explore":"浏览",
        "Show Swagger Petstore Example Apis":"显示 Swagger Petstore 示例 Apis",
        "Can't read from server.  It may not have the appropriate access-control-origin settings.":"无法从服务器读取。可能没有正确设置access-control-origin。",
        "Please specify the protocol for":"请指定协议：",
        "Can't read swagger JSON from":"无法读取swagger JSON于",
        "Finished Loading Resource Information. Rendering Swagger UI":"已加载资源信息。正在渲染Swagger UI",
        "Unable to read api":"无法读取api",
        "from path":"从路径",
        "server returned":"服务器返回"
    });

三、常用注解说明  
1、常用注解

@Api()用于类；

表示标识这个类是swagger的资源

@ApiOperation()用于方法；

表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明；

表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类

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

@ApiModelProperty()用于方法，字段

表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数

表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法

表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

@ApiResponse

返回参数

2、具体使用

@Api()用于类；

参数：

tags:表示说明，tags如果有多个值，会生成多个list

value:已废用

hidde:无效果

description:接口说明

代码：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 5][]

界面效果：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 6][]

@ApiOperation()用于方法；

value用于方法描述

notes用于提示内容

tags可以重新分组（视情况而用）

代码:

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 7][]

文档效果：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 8][]

@ApiImplicitParam() 用于方法

表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

name–参数名

value–参数说明

dataType–数据类型

paramType–参数类型

@ApiResponse

返回参数说明

response：返回的对象信息

code：返回的状态信息

message：返回的文本信息

对象信息具体注释

@ApiModelProperty

对象字段说明

value：字段名称

example: 字段说明

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200523230020692.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200523230118116.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200523230137977.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200523230309579.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[http_localhost_4040_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20200523230438352.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20200523230712258.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 6]: https://img-blog.csdnimg.cn/20200523230740205.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 7]: https://img-blog.csdnimg.cn/20200523230810739.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA_size_16_color_FFFFFF_t_70 8]: https://img-blog.csdnimg.cn/20200523230852482.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NDQ5OTM5NA==,size_16,color_FFFFFF,t_70