03、Swagger2和Springmvc整合详细记录(爬坑记录)

时间 内容 备注
2018年6月18日 基本使用 spirngmvc整合swagger2

开始之前这个系列博文基本是,在项目的使用中一些模块的内容记录,但是后期逐渐优化,不单单是整合内容。

swagger简介

1、swagger主要提供了三个功能:

  • Swagger Editor: Swagger提供的一个编辑器,用来通过Swagger提供的特定的YAML语法来编写API文档
  • Swagger Codegen: 代码生成器
  • Swagger UI: YAML语法定义我们的RESTful API,然后它会自动生成一篇排版优美的API文档,并且提供实时预览。

spirngmv 整合swagger

其实这个整合例子甚多,可以选择的使用。

推荐:官方的说明文档,虽是英文但是各个配置含义说明的很清楚建议使用,后期的优化内容根据这个执行的。

导入基本步骤:

1、修改pom.xml;添加如下swagger的依赖


<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.4.0version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.4.0version>
dependency>

2、添加如下的配置类
注意如下不是必要的步骤(swagger会使用默认配置)

package com.weir.utils;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages ="com.weir")
class ApiConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weir"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口列表 v1.1.0") // 任意,请稍微规范点
                .description("接口测试") // 任意,请稍微规范点
                .termsOfServiceUrl("http://localhost:8080/swagger-ui.html") // 将“url”换成自己的ip:port
                .version("1.1.0")
                .build();
    }
}

3、修改springmvc.xml文件;添加关于swagger的配置,内容如下:

<mvc:default-servlet-handler />

<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

<bean class="com.weir.utils.ApiConfig" />

4、代码中的使用:

@RequestMapping(value = "/login")
@ApiOperation(value = "用户登录", notes = "用户登录操作")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@ResponseBody
public ServerResponse login(String userName, String password, HttpSession session){

    ServerResponse response = userService.login (userName, password);
    if (response.isSuccess ()){
        session.setAttribute ("user",response);
    }
    return response;
}

5、运行显示

导入遇到问题记录:

最重要的内容:(自己爬坑的内容)【一定要注意

1、控制台报错内容:Getting HTTP 404 error on /swagger-ui.html but other swagger endpoint works

拦截路径改为/,不要配置成后缀的,例如:/*.do等,这会导致,wagger-ui.html页面被拦截,无法加载。


<servlet>
<servlet-name>dispatcherServletservlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServletservlet-class>
<init-param>
  <param-name>contextConfigLocationparam-name>
  <param-value>classpath:springmvc.xmlparam-value>
init-param>
servlet>
<servlet-mapping>
<servlet-name>dispatcherServletservlet-name>
<url-pattern>/url-pattern>
servlet-mapping>

当然如果你要配置成带有后缀的也是可以的,请参考如下内容:
- 解决的关键参考页面 [github的issue]
- 关于配置成为的后缀的方式解决官方文档

总结:

  • 他人博文只是具有参考意义,尽量参考官方说明文档,弄懂原理是关键
  • 推荐官方文档,中文文档和博客参差不齐
  • 不要位畏惧英文文档和资料

你可能感兴趣的:(Spring,Mybatis)