idea maven + Springmvc 整合 Swagger 总结

在日常接口开发过程中，为了方便前端同事使用我们开发的接口，通过我们需要编写各种形式的接口文档。

有Word版的 有apiDoc 版的，这次我来简单概述一下在我们已有的springmvc 项目中如何使用swagger工具

首先。我默认你本地已经存在有正常可运行的springmvc项目 且 maven 构建的

那么我们现在可以继续啦。

1.修改 pom.xm 文件 新增以下依赖

<!-- swagger2 核心依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- swagger-ui 为项目提供api展示及测试的界面 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- 集成 swagger 的时候，缺少这个 jar包是不OK的-->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.9.6</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.9.6</version>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>jstl</artifactId>
            <version>1.2</version>
            <scope>runtime</scope>
        </dependency>

2. 然后工程里新增一个包 或者在你现有的包中新增一个class ，本人是新增了一个swagger.utils包 然后再创建ApiConfig.class

代码如下：

package swargger.utils;

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
@EnableWebMvc
public class ApiConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("对外开放接口API 文档")
                .description("HTTP对外开放接口")
                .version("1.0.0")
                .termsOfServiceUrl("http://xxx.xxx.com")
                .license("LICENSE")
                .licenseUrl("http://xxx.xxx.com")
                .build();
    }

}

3. 修改resources目录下的spring的xml配置文件，有的同学喜欢命名为 application.xml  有的喜欢名为spring-mvc.xml spring-servlet.xml  你们 跟据自身实际情况吧。

新增配置如下

<mvc:default-servlet-handler />
    <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/" />
    <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/" />
 <context:component-scan base-package="swargger.*"/>

完工。我们写个测试controller来试试

package ifaster.controller.home;

import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.ModelAndView;


@Controller
@RequestMapping("student")
public class StudentController {



    //@ResponseBody//(之前我因为加了这个注解，导致页面访问一直是406错误，注释了就好啦，具体为啥我暂时还不知道)
    @ApiOperation(value = "获得所有的学生对象list", notes = "get请求，查询所有的学生。")
    @RequestMapping(value = "/getAllStudent", method = RequestMethod.GET)
    public ModelAndView getAllStudent() {
        ModelAndView mav = new ModelAndView();
        mav.setViewName("studentDisplay");
        mav.addObject("students", 123);
        return mav;
    }

    @ApiOperation(value = "根据学生的name，获得单个学生的信息", notes = "根据学生的name，查询学生对象的信息。")
    @ApiImplicitParam(name = "name", value = "学生的名称", required = true, dataType = "String")
    @ResponseBody
    @RequestMapping(value = "getStudentByName", method = RequestMethod.POST)
    public String getStudentByName(String name) {
        return "";
    }

    @ApiOperation(value = "根据学生的name和age，获得单个学生的信息", notes = "根据学生的name和age，查询学生对象的信息。")
    @ApiImplicitParams({@ApiImplicitParam(name = "name", value = "学生名称", required = true, dataType = "String"),
            @ApiImplicitParam(name = "age", value = "学生年龄", required = true, dataType = "int")})
    @ResponseBody
    @RequestMapping(value = "getStudentByNameAndAge", method = RequestMethod.POST)
    public String getStudentByName(String name, int age) {
        return "";
    }

    @ApiOperation(value = "新建学生对象到数据库", notes = "新建数据到数据库。")
    @ApiImplicitParam(name = "student", value = "学生对象", required = true, dataType = "Student")
    @ResponseBody
    @RequestMapping(value = "createNewStudent", method = RequestMethod.POST)
    public String create(@RequestBody String student) {
        return "";
    }
}

最后访问地址

http://localhost:8080/swagger-ui.html#/

大功告成！