SSM的前后端分离项目中使用swagger来自动生成API文档

关于Swagger

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

• Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
• Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
• Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
• Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger 文档提供了一个方法，使我们可以用指定的 JSON 或者 YAML 摘要来描述你的 API，包括了比如 names、order 等 API 信息。

你可以通过一个文本编辑器来编辑 Swagger 文件，或者你也可以从你的代码注释中自动生成。各种工具都可以使用 Swagger 文件来生成互动的 API 文档。

注意：用 Swagger 文件生成互动的 API 文档是最精简的，它展示了资源、参数、请求、响应。但是它不会提供你的API如何工作的其他任何一个细节。

以下是SSM的前后端分离项目中使用swagger的示例：

     1， 首先在MAVEN 项目的pom文件中引入相关依赖，依赖如下：

  （其中的jackson依赖是用于支持RESTful接口实现提供JSON格式数据的）

<!-- 第五部分：JSON，jackson依赖 -->
<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.9.8</version>
</dependency>
<!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-core -->
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-core</artifactId>
  <version>2.9.8</version>
</dependency>
<!-- 第六部分：swagger-api依赖 -->
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

   2，创建配置类SwaggerConfig和WebMvcConfig

SwaggerConfig

package com.HW_CloudComputer.webconfig.config;

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 springfox.documentation.builders.ApiInfoBuilder;
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  //必须存在
//必须存在 扫描的API controller 包
@ComponentScan(basePackages = {"com.HW_CloudComputer.api"})
public class SwaggerConfig {
    @Bean
    public Docket customDocket(){ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()); }
    private ApiInfo apiInfo(){
        Contact contact = new Contact("CuiTg","https://www.huawei.com/cn/","Ctiangui@shu.edu.cn");
        return new ApiInfoBuilder()
                .title("HW_CloudComputer项目的API接口")
                .description("API接口")
                .contact(contact)
                .version("1.1.0")
                .build();
    }
}

WebMvcConfig

package com.HW_CloudComputer.webconfig.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    public void addResourceHandlers(ResourceHandlerRegistry registry){
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

swagger-ui.html为API文档的页面

3，注意要让spring启动配置时自动扫描以上两个配置类

<!-- 扫描swagger的配置包 -->
<context:component-scan base-package="com.HW_CloudComputer.webconfig.config" />

4，编写controller，在controller中进行相应配置以便生成API文档

package com.HW_CloudComputer.api;

import com.HW_CloudComputer.model.TimeDelay;
import com.HW_CloudComputer.service.RealTimeService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "实时查询模块",description = "实时查询模块的接口信息" )
@RequestMapping("realtime")
public class RealTimeController {
    @Autowired
    private RealTimeService realTimeService;

    @ApiOperation(value = "获取实时信息",notes = "获取云电脑的实时时延数据")
    @RequestMapping(method = RequestMethod.GET)
    public TimeDelay realTime(){
        return realTimeService.findRealTime();
    }
}

@RestController
@Api(value = "参数查询模块",description = "参数查询模块的接口信息" )
@RequestMapping("/argsquery")
public class ArgsQueryController {
    @Autowired
    private ArgsQueryService argsQueryService;

    @ApiOperation(value = "以“刻”为刻度，返回数据",notes = "根据起始与结束时间获取云电脑时延数据，时间刻度为“刻")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "start_name",dataType = "String",paramType = "path",value = "查询起始时间，格式范例：2019年4月17日14点30分，start_name=201904171430"),
            @ApiImplicitParam(name = "end_time",dataType = "String",paramType = "path",value = "查询起始时间，格式范例：2019年4月17日14点30分，end_name=201904171430")
    })
    @RequestMapping(value = "/quarter/{start_time}/{end_time}",method = RequestMethod.GET)
    public List<TimeDelay> showManyQuarter(@PathVariable("start_time") String start_time, @PathVariable("end_time") String end_time){
        return  argsQueryService.findMany(start_time,end_time);
    }

5，项目完成部署到tomcat中以后访问http://localhost:8080/swagger-ui.html即可访问API文档

在web.xml中修改和新增配置：

    将*.do改为/

<servlet-mapping>
           <servlet-name>springmvc</servlet-name>
           <url-pattern>/</url-pattern>
     </servlet-mapping>