Swagger2的集成和使用

Swagger2介绍

Swagger是一款RESTful接口的文档在线自动生成、功能测试功能框架。一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，加上swagger-ui，可以有很好的呈现。

SpringBoot集成

这里选用的swagger版本为：2.8.0

1. pom依赖

    io.springfox
    springfox-swagger2
    2.8.0


    io.springfox
    springfox-swagger-ui
    2.8.0

2. 编写配置文件(Swagger2Config.java)
   主要是添加注解@EnableSwagger2和定义Docket的bean类。

@Configuration
@EnableConfigurationProperties({ AuthCodeConfig.class })
@EnableSwagger2
public class Swagger2 {

    /**
     * 基础数据请求接口
     * @param ac ac
     * @return 基础数据请求接口
     */
    @Bean
    public Docket baseApi(AuthCodeConfig ac) {
        return createApi(
                ac.toBuilder().basePackage(new String[] { "com.soulprogrammer.controller" }).groupName("基础数据接口")
                        .build());
    }

    /**
     * 数据请求接口
     * @param ac ac
     * @return artery数据请求接口
     */
    @Bean
    public Docket arteryApi(AuthCodeConfig ac) {
        return createApi(
                ac.toBuilder().basePackage(new String[] { "com.soul.ery" }).groupName("ery数据接口").build());
    }

    /**
     * 模拟请求头部
     * @param ac ac
     * @return 模拟请求头部
     */
    @Bean
    public Docket cusApi(AuthCodeConfig ac) {
        return createApi(ac);
    }

    private Docket createApi(AuthCodeConfig ac) {
        List pars = new ArrayList<>();
        if (ac.isEnable()) {
            LocalDateTime now = LocalDateTime.now();
            pars.add(header("test", "systemid", "校验码"));
            pars.add(header(AesUtil
                            .encrypt("test", ac.getKey(), DateTimeFormatter.ofPattern(ac.getIvFormat()).format(now)),
                    "authcode", "系统id"));
            pars.add(header(now.format(DateTimeFormatter.ofPattern(ac.getTimeFormat())), "timestamp", "时间戳"));
        }
        return new Docket(DocumentationType.SWAGGER_2).groupName(ac.getGroupName()).globalOperationParameters(pars)
                .genericModelSubstitutes(DeferredResult.class).apiInfo(
                        new ApiInfoBuilder().title(ac.getTitle()).description(ac.getDesc()).version(ac.getVersion())
                                .build()).select()
                .apis(e -> Optional.ofNullable(e).map(RequestHandler::declaringClass).map(Class::getPackage)
                        .map(Package::getName).map(e1 -> StringUtils.startsWithAny(e1, ac.getBasePackage()))
                        .orElse(true)).paths(PathSelectors.any()).build();
    }

    private Parameter header(String value, String systemid, String name) {
        return new ParameterBuilder().name(systemid).description(name).modelRef(new ModelRef("string"))
                .parameterType("header").required(false).defaultValue(value).build();
    }

3. 添加文档内容(一般上是在Controller，请求参数上进行注解，这里以上章节的UserController进行配置)
   UserController

@RestController
@RequestMapping("/user")
@Api(tags="用户API")
public class UserController {
 
    @Autowired
    IUserService userService;
 
    @PostMapping("add")
    @ApiOperation(value="用户新增")
    //正常业务时， 需要在user类里面进行事务控制，控制层一般不进行业务控制的。
    //@Transactional(rollbackFor = Exception.class)
    public Map addUser(@Valid @RequestBody UserReq userReq){
 
        User user = new User();
        user.setCode(userReq.getCode());
        user.setName(userReq.getName());
        //由于设置了主键策略 id可不用赋值 会自动生成
        //user.setId(0L);
        userService.insert(user);
        Map result = new HashMap();
        result.put("respCode", "01");
        result.put("respMsg", "新增成功");
        //事务测试
        //System.out.println(1/0);
        return result;
    }

通过http://ip:port/swagger-ui.html登录界面

配置简阅

@EnableSwagger2
@Configuration
public class SwaggerConfig {
 
    //是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;
 
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                // 是否开启
                .enable(swaggerEnabled).select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("cn.lqdev.learning.springboot.chapter10"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot-Swagger2集成和使用-demo示例")
                .description("oKong | 趔趄的猿")
                // 作者信息
                .contact(new Contact("swh", "https://blog.csdn.net/Soul_Programmer_Swh"))
                .version("1.0.0")
                .build();
    }
}