Swagger技术

Swagger

1、Swagger简介

　　swagger是一个简单但功能强大的API表达工具，使用Swagger生成API，我们可以得到交互式文档。简单来说就是前台人员在写代码的时候，可以通过访问连接，获取后台返回的json数据包，进行页面效果测试。后台人员在前端页面没有页面的时候也可以进行数据跑通测试。

　　程序流程：引入swagger依赖，由于接口测试页面并不是我们自己写的静态资源页面，静态页面资源来源于swagger的jar包中，所以需要在启动类中配置相应的资源映射路径。swaggerConfig中配置接口，这里接口有两种，一是Api注解扫描，在codeController中，方法上使用@ApiOperation，进行参数接收，代码生成。二是包扫描配置，将controller包下的所有访问接口展示出来，可以进行单对单的访问，传入对应参数值返回页面。

2、使用界面

　　两种测试方式：使用注解接口配置访问页面，传入参数，得到返回的json值

 使用包扫描，对全部的访问接口进行展示，也可以传递参数

3、开发流程

引入依赖

        <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
        </dependency>

swaggerConfig.java类开发

　　这里扫描有两个方式：一种是包含注解扫描，如果方法、方法类上有ApiOperation注解，就会进行接口处理；

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                         //这里采用包含注解的方式来确定要显示的接口

　　一种是包扫描，直接指定controller包下的所有请求方法；

.apis(RequestHandlerSelectors.basePackage("com.stylefeng.guns.modular.system.controller"))    //这里采用包扫描的方式来确定要显示的接口

　　完整配置类的代码

package com.stylefeng.guns.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;

/**
 * swagger配置类
 *
 * @author fengshuonan
 * @date 2017年6月1日19:42:59
 */
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "guns", name = "swagger-open", havingValue = "true")
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //去controller找是否有ApiOperation注解，如果有ApiOperation注解，就会被Spring管理  
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))                         //这里采用包含注解的方式来确定要显示的接口
                //包扫描  这里就会例举出所有controller下的所有类型方法  这个对单个连接进行传递值
                //.apis(RequestHandlerSelectors.basePackage("com.stylefeng.guns.modular.system.controller"))    //这里采用包扫描的方式来确定要显示的接口
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Guns Doc")
                .description("Guns Api文档")
                .termsOfServiceUrl("http://git.oschina.net/naan1993/guns")
                .contact("stylefeng")
                .version("2.0")
                .build();
    }

}

controller访问

注解扫描访问

package com.stylefeng.guns.modular.system.controller;

import com.stylefeng.guns.common.annotion.Permission;
import com.stylefeng.guns.common.constant.Const;
import com.stylefeng.guns.common.exception.BizExceptionEnum;
import com.stylefeng.guns.common.exception.BussinessException;
import com.stylefeng.guns.core.base.controller.BaseController;
import com.stylefeng.guns.core.template.config.ContextConfig;
import com.stylefeng.guns.core.template.engine.SimpleTemplateEngine;
import com.stylefeng.guns.core.template.engine.base.GunsTemplateEngine;
import com.stylefeng.guns.core.util.ToolUtil;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * 代码生成控制器
 *
 * @author fengshuonan
 * @Date 2017-05-23 18:52:34
 */
@Controller
@RequestMapping("/code")
public class CodeController extends BaseController {

    private String PREFIX = "/system/code/";

    /**
     * 跳转到代码生成首页
     */
    @RequestMapping("")
    public String index() {
        return PREFIX + "code.html";
    }

    /**
     * 代码生成
     */
    @ApiOperation("生成代码")  //这里再注解配置完成之后，进入这个类   说明方法的作用
    @RequestMapping(value = "/generate", method = RequestMethod.POST)
    @ResponseBody
    @Permission(Const.ADMIN_NAME)
    //RequestParam 参数字段名称   这里还可以ApiImplicitParams 一个数组  ApiImplicitParam单个参数放入数组
    public Object add(@ApiParam(value = "模块名称",required = true) @RequestParam  String moduleName,
                      @RequestParam String bizChName,  //这里表示页面传入的参数名
                      @RequestParam String bizEnName,
                      @RequestParam String path) {
        if (ToolUtil.isOneEmpty(bizChName, bizEnName)) {
            throw new BussinessException(BizExceptionEnum.REQUEST_NULL);
        }
        
        ContextConfig contextConfig = new ContextConfig();
        contextConfig.setBizChName(bizChName);
        contextConfig.setBizEnName(bizEnName);
        contextConfig.setModuleName(moduleName);
        if (ToolUtil.isNotEmpty(path)) {
            contextConfig.setProjectPath(path);
        }

        GunsTemplateEngine gunsTemplateEngine = new SimpleTemplateEngine();
        gunsTemplateEngine.setContextConfig(contextConfig);
        gunsTemplateEngine.start();

        return super.SUCCESS_TIP;
    }
}

在启动类中还要配置相应的资源访问映射路径，接口页面不是我们自己写的，是引入的依赖包的静态资源。

package com.stylefeng.guns;

import com.stylefeng.guns.config.properties.GunsProperties;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

/**
 * SpringBoot方式启动类
 *
 * @author stylefeng
 * @Date 2017/5/21 12:06
 */
@SpringBootApplication
public class GunsApplication extends WebMvcConfigurerAdapter{

    protected final static Logger logger = LoggerFactory.getLogger(GunsApplication.class);

    @Autowired
    GunsProperties gunsProperties;

    /**
     * 增加swagger的支持
     */
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        if(gunsProperties.getSwaggerOpen()){
            //请求页面的样式是从依赖的jar来的 ，要使用这些资源比如进行引入   springmvc去寻找这些资源
            registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            //告诉spring-mvc请求这个路径  就表示请求特定的静态资源
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }

    public static void main(String[] args) {
        SpringApplication.run(GunsApplication.class, args);
        logger.info("GunsApplication is success!");
    }
}

注解使用

@ApiOperation

用在方法上，说明方法的作用。

@ApiImplicitParams

用在方法上包含一组参数说明

@ApiImplicitParam

用在@ApiImplicitParam中，指定一个参数的作用

paramType：参数放在哪个地方 header-->请求参数的获取：

@RequestHeader query-->请求参数的获取：

@RequestParam path（用于restful接口）-->请求参数的获取：

@PathVariable body（@RequestBody）

form（表单提交）

name：参数名

dataType：参数类型

required：参数是否必须传

value：参数的意思

defaultValue：参数的默认值

由于接口测试页面并不是我们自己写的静态资源页面，静态页面资源来源于swagger的jar包中，所以需要在启动类中配置相应的资源映射路径。