项目Swagger化

最新推荐文章于 2025-07-06 14:51:49 发布

ShuaiLewis

最新推荐文章于 2025-07-06 14:51:49 发布

阅读量371

点赞数

CC 4.0 BY-SA版权

分类专栏： java

本文链接：https://blog.csdn.net/u010986518/article/details/88042797

java 专栏收录该内容

6 篇文章

订阅专栏

一、需要引入的依赖包

前两个是关于swagger的包，第三个包是配置的时候返回Docket对象需要引入的包。

注:我在引入第三个包的版本过高的时候项目起不来

<!-- 引入swagger依赖 -->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.5.0</version>
 </dependency>

 <!-- 引入swagger-UI依赖 -->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.5.0</version>
 </dependency>

 <!-- 引入springfox-spring-web包 -->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-spring-web</artifactId>
     <version>2.5.0</version>
 </dependency>

二、swagger-ui.html代码

1.在resources下面创建文件夹META-INF，在META-INF下面创建文件夹resources，在resources创建swagger-ui.html，如下：

在这里插入图片描述

2.swagger-ui.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>

三、配置Swagger

创建一个Swagger2Config类，代码如下：

package com.baozun.chenda.config;

import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Author chenshuai
 * @data 2019/2/28 15:48
 */
@SpringBootConfiguration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket docket () {
        StringBuilder path = new StringBuilder();
        //     /chen是controller下面的类层面的url
        path.append("(/swagger-demo/.*")
            .append("|/chen/.*")
            .append("|/menu-item/.*")
            .append(")");

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .useDefaultResponseMessages(false)
                .select()
                .paths(PathSelectors.regex(path.toString()))
                .build();
    }

    private ApiInfo apiInfo () {
        return new ApiInfoBuilder()
                .title("菜单服务接口文档")
                .version("1.0")
                .build();
    }
}

上面添加路径使用的是：

 .paths(PathSelectors.regex(path.toString()))

还有一种是使用下面的代替上面的语句：

.apis(RequestHandlerSelectors.basePackage("com.baozun.ecs.oms4.auth"))

四、在CustomerWebMVCConfig添加关于seagger的配置

package com.baozun.chenda.config;

import com.baozun.chenda.interceptor.ApiInterceptor;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

/**
 * @Author chenshuai
 * @data 2019/1/22 20:49
 */
@SpringBootConfiguration
public class CustomerWebMVCConfig extends WebMvcConfigurationSupport {
    /**
    @Override
    public void addInterceptors(InterceptorRegistry registry){
        super.addInterceptors(registry);
        registry.addInterceptor(new ApiInterceptor());
    }*/

    @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/");
    }
}

五、在Controller添加@Api注释，在方法添加@ApiOperation注释，在model加@ApiModel注解，在属性加@ApiModelOperation注解

1.示例：在Controller添加@Api注释，在方法添加@ApiOperation注释

package com.baozun.chenda.controller;

import com.baozun.chenda.config.Aliyun;
import com.baozun.chenda.config.NewYear;
import com.baozun.chenda.manager.InvoiceManager;
import com.baozun.chenda.model.Invoice;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.log4j.Log4j2;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;

@Log4j2
@RestController
@RequestMapping("/chen")
@Api(tags = "哈喽测试接口")
public class HelloController {
    @Autowired
    private InvoiceManager invoiceManager;

    @Autowired
    private Aliyun aliyun;

    @GetMapping(value = "/printHello")
    @ApiOperation(value = "测试Hello World", notes ="测试Hello World")
    public String printHello(){
        return "Hello World";
    }

    @GetMapping(value = "/code")
    @ApiOperation(value = "测试code", notes ="测试code")
    public String printString(@RequestParam("code") String code) {
        if("kkk".equals(code)) {
            throw new RuntimeException();
        }
        return "print" + code;
    }

    @PostMapping("/validate")
    @ApiOperation(value = "订单接口", notes ="订单接口")
    public String authorize(@RequestBody @Valid Invoice invoice, BindingResult ret){
        invoiceManager.validateParam(invoice, ret);
        return "kkk";
    }

    @GetMapping(value = "/aliyun")
    @ApiOperation(value = "阿里云接口", notes ="阿里云接口")
    public String printValueTest() {
        return "appkey : " + aliyun.getAppKey() + ", appSecret : " + aliyun.getAppSecret();
    }
}

2.在model加@ApiModel注解，在属性加@ApiModelOperation注解

package com.baozun.chenda.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import lombok.ToString;

import javax.validation.constraints.NotBlank;
import java.io.Serializable;

/**
 * @Author chenshuai
 * @data 2019/1/25 13:53
 */
@Getter
@Setter
@ToString
@ApiModel(value = "发票")
public class Invoice implements Serializable {
    @NotBlank(message = "系统编码为空")
    @ApiModelProperty(value = "系统编码为空")
    private String systenCode;

    @NotBlank(message = "平台编码为空")
    @ApiModelProperty(value = "平台编码为空")
    private String platformCode;

    @ApiModelProperty(value = "系统编码为空")
    @NotBlank(message = "系统编码为空")
    private String serioNo;
}