精通SpringBoot——第九篇：整合Swagger在线文档-白红宇

开发中最烦的一件事是什么？当你全心全意思考的时候，前端笑眯眯的过来了：“大哥，你没告诉我该传什么参数！”......然后一堆吧啦吧啦扯淡，好了，前端大佬心满意足的走了，你以为事情也就这么结束了。滴滴滴，微信消息来了：“接口怎么不通啊，你是不是代码写的有问题啊？”一顿操作后，登上控制台，日志一看。啊~（我们一起学土拨鼠叫）内心是崩溃的... 参数少了，参数类型不对，格式不对，各种。这时候很想丢个文档给前端：你自己看吧！然而，写文档真的太麻烦了，懒...只好去逛逛论坛，百度谷歌下有没有什么生成在线文档的工具了，结果如你所愿，还真有。今儿个，咱们就来走一波spring boot 整合 swagger 生成在线文档。（呼~~爽，感觉用了这个，就可以不用被前端大佬“骚扰”了）。介绍两种集成swagger的方式，越用越爽。写文档的时候可以用来和基友尬聊了（编程五分钟，扯淡两小时，一天就这么没了...）

第一招 Without Starter

新建项目,pom 文件加上两个swagger必要的依赖。


                
     
      io.springfox
                 
     
      springfox-swagger2
                 
     
      ${swagger.version}
             
            
                
     
      io.springfox
                 
     
      springfox-swagger-ui
                 
     
      ${swagger.version}

Swagger的配置文件

@Configuration@EnableSwagger2public class SwaggerConfig {    /**     * swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。     *     * @return     * @Api：修饰整个类，描述Controller的作用     * @ApiOperation：描述一个类的一个方法，或者说一个接口     * @ApiParam：单个参数描述     * @ApiModel：用对象来接收参数     * @ApiProperty：用对象接收参数时，描述对象的一个字段     * @ApiResponse：HTTP响应其中1个描述     * @ApiResponses：HTTP响应整体描述     * @ApiIgnore：使用该注解忽略这个API     * @ApiError：发生错误返回的信息     * @ApiImplicitParam：一个请求参数     * @ApiImplicitParams：多个请求参数     */    @Bean    public Docket createRestApi() {        /**添加head参数start*/        ParameterBuilder tokenPar = new ParameterBuilder();        List
    
      pars = new ArrayList
     
      ();        tokenPar.name("authorization").description("令牌").modelRef(new ModelRef("string")).parameterType("header").required(false).build();        pars.add(tokenPar.build());        //添加head参数end        return new Docket(DocumentationType.SWAGGER_2)                .groupName("com.developlee.HangZhou.ZheJiang")                .select()                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //有该注解的生成doc                .apis(RequestHandlerSelectors.basePackage("com.developlee.swagger"))   // 自行修改为自己的包路径                .paths(PathSelectors.any())                .build()                .globalOperationParameters(pars) //set Header                .apiInfo(apiInfo());    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("DevelopLee的Swagger在线文档")                .description("嗯哼嗯哼额~~~swagger文档很强！")                .termsOfServiceUrl("http://github.com/developlee")                .version("1.0")                .build();    }}

写个Controller类测试

@RestControllerpublic class UserController {    @GetMapping("/userInfo")    @ApiOperation(notes = "获取用户信息", value = "get user info")    public String getUserInfo(){        return "getUserInfo";    }    @PostMapping("/addUser")    @ApiOperation(notes = "添加用户信息", value = "add user info")    @ApiImplicitParam(value = "添加用户", name = "add user", dataType = "java.lang.String", required = true)    public String addUser(String str){        return "addUser";    }}

启动项目...访问 localhost:8080/swagger-ui.html（我滴个龟龟，这就好了？）感动到哭，前端大佬们， see you la la~~（事实上我去找他们聊天了，感受下这个文档带给后端开发人员的福利，尤其是惰性开发人员，比如在座的所有人)

第二招 With swagger-spring-boot-starter

这里介绍一个相当牛逼的工具，来自spring4all.com社区开源的。接下来我们就用这个依赖包开发swagger 文档。

pom.xml依赖


            
     
      com.spring4all
             
     
      swagger-spring-boot-starter
             
     
      1.7.1.RELEASE

@EnableSwagger2Doc开启文档

@SpringBootApplication@EnableSwagger2Docpublic class SwaggerStarterApplication {    public static void main(String[] args) {        SpringApplication.run(SwaggerStarterApplication.class, args);    }}

配置示例：

swagger.enabled=trueswagger.title=spring-boot-starter-swaggerswagger.description=Starter for swagger 2.xswagger.version=1.7.1.RELEASEswagger.license=Apache License, Version 2.0swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.htmlswagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swaggerswagger.contact.name=developleeswagger.contact.url=http://github.com/developleeswagger.contact.email=developlee@163.comswagger.base-package=com.developleeswagger.base-path=/**swagger.exclude-path=/error, /ops/**swagger.globalOperationParameters[0].name=name oneswagger.globalOperationParameters[0].description=some description oneswagger.globalOperationParameters[0].modelRef=stringswagger.globalOperationParameters[0].parameterType=headerswagger.globalOperationParameters[0].required=trueswagger.globalOperationParameters[1].name=name twoswagger.globalOperationParameters[1].description=some description twoswagger.globalOperationParameters[1].modelRef=stringswagger.globalOperationParameters[1].parameterType=bodyswagger.globalOperationParameters[1].required=false// 取消使用默认预定义的响应消息,并使用自定义响应消息swagger.apply-default-response-messages=falseswagger.global-response-message.get[0].code=401swagger.global-response-message.get[0].message=401getswagger.global-response-message.get[1].code=500swagger.global-response-message.get[1].message=500getswagger.global-response-message.get[1].modelRef=ERRORswagger.global-response-message.post[0].code=500swagger.global-response-message.post[0].message=500postswagger.global-response-message.post[0].modelRef=ERROR

配置说明--默认配置

- swagger.enabled=是否启用swagger，默认：true- swagger.title=标题- swagger.description=描述- swagger.version=版本- swagger.license=许可证- swagger.licenseUrl=许可证URL- swagger.termsOfServiceUrl=服务条款URL- swagger.contact.name=维护人- swagger.contact.url=维护人URL- swagger.contact.email=维护人email- swagger.base-package=swagger扫描的基础包，默认：全扫描- swagger.base-path=需要处理的基础URL规则，默认：/**- swagger.exclude-path=需要排除的URL规则，默认：空- swagger.host=文档的host信息，默认：空- swagger.globalOperationParameters[0].name=参数名- swagger.globalOperationParameters[0].description=描述信息- swagger.globalOperationParameters[0].modelRef=指定参数类型- swagger.globalOperationParameters[0].parameterType=指定参数存放位置,可选header,query,path,body.form- swagger.globalOperationParameters[0].required=指定参数是否必传，true,false

Path设置

management.context-path=/opsswagger.base-path=/**swagger.exclude-path=/ops/**, /error

上面的设置将解析所有除了/ops/开始以及spring boot自带/error请求路径。

其中，exclude-path可以配合management.context-path=/ops设置的spring boot actuator的context-path来排除所有监控端点。

分组配置

- swagger.docket.
    
     .title=标题- swagger.docket.
     
      .description=描述- swagger.docket.
      
       .version=版本- swagger.docket.
       
        .license=许可证- swagger.docket.
        
         .licenseUrl=许可证URL- swagger.docket.
         
          .termsOfServiceUrl=服务条款URL- swagger.docket.
          
           .contact.name=维护人- swagger.docket.
           
            .contact.url=维护人URL- swagger.docket.
            
             .contact.email=维护人email- swagger.docket.
             
              .base-package=swagger扫描的基础包，默认：全扫描- swagger.docket.
              
               .base-path=需要处理的基础URL规则，默认：/**- swagger.docket.
               
                .exclude-path=需要排除的URL规则，默认：空- swagger.docket.
                
                 .name=参数名- swagger.docket.
                 
                  .modelRef=指定参数类型- swagger.docket.
                  
                   .parameterType=指定参数存放位置,可选header,query,path,body.form- swagger.docket.
                   
                    .required=true=指定参数是否必传，true,false- swagger.docket.
                    
                     .globalOperationParameters[0].name=参数名- swagger.docket.
                     
                      .globalOperationParameters[0].description=描述信息- swagger.docket.
                      
                       .globalOperationParameters[0].modelRef=指定参数存放位置,可选header,query,path,body.form- swagger.docket.
                       
                        .globalOperationParameters[0].parameterType=指定参数是否必传，true,false

更多移步至。

最后，以上示例代码可在我的中找到。

我的个人公众号：developlee的潇洒人生。

关注了也不一定更新，更新就不得了了。