springcloud项目引入swagger

【项目背景】

       Springcloud项目，之前用DOCLever管理项目接口文档，再用postman调用测试接口，觉得不是很方便，而且公司改网络后，之前的接口文档丢失，所以改用swagger管理接口文档。

swagger是一个方便后端编写接口文档的开源项目，并提供界面化测试。

【工具对比】

 

【实现方案】

• 在pom.xml文件中添加maven依赖

<!-- Swagger核心包 start -->
<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>
<!-- Swagger核心包 end -->

• 新建配置类

@Configuration

@EnableSwagger2

public class Swagger2 {

    /**

     * 通过 createRestApi函数来构建一个DocketBean

     * 函数名,可以随意命名,喜欢什么命名就什么命名

     */

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

                .apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容

                .select()

                //控制暴露出去的路径下的实例

                //如果某个接口不想暴露,可以使用以下注解

                //@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下

                .apis(RequestHandlerSelectors.basePackage("com.example.zwd.springbootswagger2.controller"))

                .paths(PathSelectors.any())

                .build();

    }

    //构建 api文档的详细信息函数

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

                //页面标题

                .title("Spring Boot Swagger2 构建RESTful API")

                //条款地址

                .termsOfServiceUrl("http://despairyoke.github.io/")

                .contact("zwd")

                .version("1.0")

                //描述

                .description("API 描述")

                .build();

    }

}

• 新建测试controller类

@RestController

public class UserController {

    @ApiOperation(value = "接口的功能介绍",notes = "提示接口使用者注意事项",httpMethod = "GET")

    @ApiImplicitParam(dataType = "string",name = "name",value = "姓名",required = true)

    @RequestMapping(value = "/")

    public String index(String name) {

        return "hello "+ name;

    }

}

 

此时启动项目，输入http://localhost:8080/swagger-ui.html，能够看到如下页面，说明已经配置成功了：

【遇见问题】

     访问http://localhost:8080/swagger-ui.html 报 404，如下所示

• 出现原因

       swagger-ui.html 是这个.html后缀的文件，springboot默认为是静态文件，静态文件默认是放在resource/static或者template里面的，但是这个swagger-ui.html 我们并没有页面，所以这种情况下我们就要给这个swagger-ui.html开“绿灯”添加例外。

 

• 解决方法

在WebMvcConfig中添加上静态资源路径映射

/**

 * 在SpringBoot2.0及Spring 5.0 WebMvcConfigurerAdapter已被废弃，目前找到解决方案就有

 * 1 直接实现WebMvcConfigurer （官方推荐）

 * 2 直接继承WebMvcConfigurationSupport

 * @ https://blog.csdn.net/lenkvin/article/details/79482205

 */

@Configuration

public class WebMvcConfig extends WebMvcConfigurerAdapter {



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



    }