精通Spring Boot——第九篇:整合Swagger在线文档

原创
2018/10/14 21:44
阅读数 1.1K

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

    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

Swagger的配置文件

@Configuration
@EnableSwagger2
public 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<Parameter> pars = new ArrayList<Parameter>();
        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类测试

@RestController
public 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~~(事实上我去找他们聊天了,感受下这个文档带给后端开发人员的福利,尤其是惰性开发人员,比如在座的所有人) image

第二招 With swagger-spring-boot-starter

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

  <dependency>
        <groupId>com.spring4all</groupId>
        <artifactId>swagger-spring-boot-starter</artifactId>
        <version>1.7.1.RELEASE</version>
  </dependency>

@EnableSwagger2Doc开启文档

@SpringBootApplication
@EnableSwagger2Doc
public class SwaggerStarterApplication {

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

###配置示例:

swagger.enabled=true

swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.7.1.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=developlee
swagger.contact.url=http://github.com/developlee
swagger.contact.email=developlee@163.com
swagger.base-package=com.developlee
swagger.base-path=/**
swagger.exclude-path=/error, /ops/**

swagger.globalOperationParameters[0].name=name one
swagger.globalOperationParameters[0].description=some description one
swagger.globalOperationParameters[0].modelRef=string
swagger.globalOperationParameters[0].parameterType=header
swagger.globalOperationParameters[0].required=true
swagger.globalOperationParameters[1].name=name two
swagger.globalOperationParameters[1].description=some description two
swagger.globalOperationParameters[1].modelRef=string
swagger.globalOperationParameters[1].parameterType=body
swagger.globalOperationParameters[1].required=false

// 取消使用默认预定义的响应消息,并使用自定义响应消息
swagger.apply-default-response-messages=false
swagger.global-response-message.get[0].code=401
swagger.global-response-message.get[0].message=401get
swagger.global-response-message.get[1].code=500
swagger.global-response-message.get[1].message=500get
swagger.global-response-message.get[1].modelRef=ERROR
swagger.global-response-message.post[0].code=500
swagger.global-response-message.post[0].message=500post
swagger.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=/ops

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

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

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

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

更多移步至 github.com

最后,以上示例代码可在我的github.com-swagger-starter以及github.com-swagger及中找到。 我的个人公众号:developlee的潇洒人生。 关注了也不一定更新,更新就不得了了。 qrcode_for_gh_2bd3f44efa21_258

展开阅读全文
打赏
1
31 收藏
分享
加载中

引用来自“developlee的潇洒人生”的评论

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?

引用来自“developlee的潇洒人生”的评论

Spring Boot 2.0.4.RELEASE Swagger 2.7.0

引用来自“天青色有雨”的评论

项目中用的spring boot版本还是1.5.x的,请问spring boot1.5.x能否整合swagger 2.9.2?据了解2.9版本视图化界面更完善些,2.7版本还是有点差距的
版本差距不大,另外事实上,我觉得您应该自己动手去尝试,这样远比我告诉您强得多

各个版本我都已经尝试整合了,真实的效果还是得靠开发规范的约束,不过在测试阶段是可以用的
2018/10/21 22:56
回复
举报
liululee博主

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?

引用来自“developlee的潇洒人生”的评论

Spring Boot 2.0.4.RELEASE Swagger 2.7.0

引用来自“天青色有雨”的评论

项目中用的spring boot版本还是1.5.x的,请问spring boot1.5.x能否整合swagger 2.9.2?据了解2.9版本视图化界面更完善些,2.7版本还是有点差距的
版本差距不大,另外事实上,我觉得您应该自己动手去尝试,这样远比我告诉您强得多
2018/10/21 20:30
回复
举报

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?

引用来自“developlee的潇洒人生”的评论

Spring Boot 2.0.4.RELEASE Swagger 2.7.0
项目中用的spring boot版本还是1.5.x的,请问spring boot1.5.x能否整合swagger 2.9.2?据了解2.9版本视图化界面更完善些,2.7版本还是有点差距的
2018/10/15 09:17
回复
举报
liululee博主

引用来自“天青色有雨”的评论

请问整合的是2.9版本的么?spring boot的版本是多少?
Spring Boot 2.0.4.RELEASE Swagger 2.7.0
2018/10/14 22:29
回复
举报
请问整合的是2.9版本的么?spring boot的版本是多少?
2018/10/14 22:25
回复
举报
更多评论
打赏
5 评论
31 收藏
1
分享
返回顶部
顶部