Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API与接口方法,参数等保存同步,大大减少了接口开发人员的工作量.这个例子是我本地运行正常的,完整demo在文章最后。

  第一步:在pom.xml引入相关jar 

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>
        
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-core</artifactId>  
            <version>2.8.0</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-databind</artifactId>  
            <version>2.6.3</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-annotations</artifactId>  
            <version>2.6.3</version>  
        </dependency>  

  第二步:配置spring-servlet.xml

<!-- 激活@controller模式 -->
    <mvc:annotation-driven />
    <!-- 配置包扫描位置(会在此包下扫描@controller控制器) -->
    <context:component-scan base-package="com.scan,com.bean" />
<!--  swagger静态文件路径 -->
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/" cache-period="31556926"/>
    <mvc:default-servlet-handler />
    <bean class="com.scan.config.SwaggerConfig" /> 

  第三步:编写SwaggerConfig

    

package com.scan.config;
   
import com.google.common.base.Predicate;

import org.springframework.beans.factory.annotation.Autowired;
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.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;

import java.util.List;

import static com.google.common.base.Predicates.or;
import static com.google.common.collect.Lists.newArrayList; 
 
@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com.scan.controller"})   
@EnableWebMvc
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean
    public Docket customDocket() {
        //
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("老王", "https://www.baidu.me", "baidu_666@icloud.com");
        return new ApiInfo("Blog前台API接口",//大标题 title
                "Swagger测试demo",//小标题
                "0.0.1",//版本
                "www.baidu.com",//termsOfServiceUrl
                contact,//作者
                "Blog",//链接显示文字
                "https://www.baidu.me"//网站链接
        );
    }
    
      
}

  第四步:控制层的配置

  

@Controller
@RequestMapping("/userController")
@Api(tags = "二:用户信息") //swagger分类标题注解
public class UserController {

    @RequestMapping(value = "/listCompound", method = RequestMethod.GET)
    @ResponseBody
  //swagger返回值注解 @ApiResponses(value
= { @ApiResponse(code = 500, message = "系统错误"), @ApiResponse(code = 200, message = "0 成功,其它为错误,返回格式:{code:0,data[{}]},data中的属性参照下方Model", response = UserVo.class) }) @ApiOperation(httpMethod = "GET", value = "个人信息")//swagger 当前接口注解 public String listCompound( @ApiParam(required = true, name = "start", value = "start") int start, int limit, @ApiParam(required = false, name = "userName", value = "名称模糊查询") String userName) { List<UserVo> data = new ArrayList<UserVo>(); String msg = data.size() > 0 ? "" : "没有查询到相关记录"; Result result = new Result(); result.setMsg(msg); result.setCode(0); result.setData(data); return JSONObject.toJSONString(result); }

  第五步:下载swaggerUi,将下载后的文件解压,将dist目录下的文件,复制到webapp下的swagger目录中(这个目录的名字自定义,但要和spring-servert.xml中(<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/") 的名称要一致,修改index.html中文档加载的地址.

window.onload = function() {
  
  // Build a system
  const ui = SwaggerUIBundle({
    //url: "http://petstore.swagger.io/v2/swagger.json",
    url:"http://127.0.0.1:8080/swagger-spring/v2/api-docs.do",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

  如果以上配置正确,在浏览器中输入http://127.0.0.1:8080/swagger-spring/swagger/index.html,将会出现如下界面:

  

 

 swagger注解说明

    1、与模型相关的注解,用在bean上面

    @ApiModel:用在bean上,对模型类做注释;

    @ApiModelProperty:用在属性上,对属性做注释

  2、与接口相关的注解

    @Api:用在controller上,对controller进行注释;

    @ApiOperation:用在API方法上,对该API做注释,说明API的作用;

    @ApiImplicitParams:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明; 

    @ApiImplicitParam:用在@ApiImplicitParams注解中,也可以单独使用,说明一个请求参数的各个方面,该注解包含的常用选项有:

      paramType:参数所放置的地方,包含query、header、path、body以及form,最常用的是前四个。

      name:参数名;

      dataType:参数类型,可以是基础数据类型,也可以是一个class;

      required:参数是否必须传;

      value:参数的注释,说明参数的意义;

      defaultValue:参数的默认值;

    

    @ApiResponses:通常用来包含接口的一组响应注解,可以简单的理解为响应注解的集合声明;

    @ApiResponse:用在@ApiResponses中,一般用于表达一个响应信息

      code:即httpCode,例如400 

      message:信息,例如"操作成功"

      response = UserVo.class  这里UserVo是一个配置了@ApiModel注解的对像,该是对像属性已配置 @ApiModelProperty,swagger可以通过这些配置,生 成接口返回值

  

  注意事项:
  1. 为了在swagger-ui上看到输出,至少需要两个注解:@Api和@ApiOperation
  2. 即使只有一个@ApiResponse,也需要使用@ApiResponses包住
  3. 对于@ApiImplicitParam的paramType:query、form域中的值需要使用@RequestParam获取, header域中的值需要使用@RequestHeader来获取,path域中的值需要使用@PathVariable来获取,body域中的值使用@RequestBody来获取,否则可能出错;而且如果paramType是body,name就不能是body,否则有问题,与官方文档中的“If paramType is "body", the name should be "body"不符。

  完整demo下载地址:https://github.com/jlq023/spring_swaggerDemo