springboot整合swagger2接口文档

现在的很多项目都是用前后端分离工作模式，这样让各个岗位能够专注的各司其职，但是会带来一些问题：前后端沟通会带来比较大的成本，而且后端自测接口也不是很方便；在这里给大家推荐一个非常好用的插件 swagger

官方文档地址：https://swagger.io/
第三方文档地址（个人推荐）： https://doc.xiaominfo.com/guide

第一步

pom中添加依赖

        <!-- swagger-ui 核心包-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>
        <!-- 使用第三方swagger-ui 参考    https://doc.xiaominfo.com/guide/-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.3</version>
        </dependency>

第二步

添加配置

package cn.mztjt.hephaistos.bapi.config;

@Log4j2
//增强 swagger 可实现接口排序
@EnableSwaggerBootstrapUI
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    /**
     * 创建一个Docket对象
     * 调用select()方法，
     * 生成ApiSelectorBuilder对象实例，该对象负责定义外漏的API入口
     * 通过使用RequestHandlerSelectors和PathSelectors来提供Predicate，在此我们使用any()方法，将所有API都通过Swagger进行文档管理
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        log.debug("正在初始化Swagger......");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo("木木服务接口"))
                .select()
// 需要进行展示的接口包地址
.apis(RequestHandlerSelectors.basePackage("com.mumu.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(String title) {
        return new ApiInfoBuilder()
                //大标题
                .title(title)
                //详细描述
                .description("接口文档描述......")
                .termsOfServiceUrl("")
                //作者
                .contact(new Contact("Wangzhen", "", "nice364837785@gmail.com"))
                .version("1.0")
                .build();
    }
}

第三步

使用

package cn.mumu.controller;

/**
 * 
 *
 * @author Wangzhen
 * @email 364837785@qq.com
 * @date 2020-02-22 09:13:45
 */
@Api(tags = "这个类底下的所有接口描述。例如：学生相关接口")
@Log4j2
@RestController
@RequestMapping("stu")
public class StuController{

    @Autowired
    private StuService stuService;


    @ApiOperation(value = "信息", position = 1,notes="根据id获取学生信息")
    @RequestMapping(value = "/info/{id}", method = RequestMethod.GET)
    public SzResult<StuServiceEntity> info(@RequestParam("字段描述 id 主键") @PathVariable("id") Long id) {
        StuServiceEntity stu = stuService.info(id);
        return new SzResult().success(stu);
    }

}

第四步

访问 http://127.0.0.1:8080/doc.html

看到这个页面就已经大功告成了！

遇到的问题：

访问/doc.html 404 报错

解决方案：

1.在springmvc层添加资源处理器

@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决 doc.html 404 报错
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    }

2.如果项目中使用shiro引起的资源不能访问，那么就需要对这些资源进行放行。