精通SpringBoot——第九篇：整合Swagger在线文档

2022-02-14 03:06:54

开发中最烦的一件事是什么？当你全心全意思考的时候，前端笑眯眯的过来了：“大哥，你没告诉我该传什么参数！”......然后一堆吧啦吧啦扯淡，好了，前端大佬心满意足的走了，你以为事情也就这么结束了。滴滴滴，微信消息来了：“接口怎么不通啊，你是不是代码写的有问题啊？”一顿操作后，登上控制台，日志一看。啊~（我们一起学土拨鼠叫）内心是崩溃的... 参数少了，参数类型不对，格式不对，各种。这时候很想丢个文档给前端：你自己看吧！然而，写文档真的太麻烦了，懒...只好去逛逛论坛，百度谷歌下有没有什么生成在线文档的工具了，结果如你所愿，还真有。今儿个，咱们就来走一波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~~（事实上我去找他们聊天了，感受下这个文档带给后端开发人员的福利，尤其是惰性开发人员，比如在座的所有人)
精通SpringBoot——第九篇：整合Swagger在线文档

第二招 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中找到。
我的个人公众号：developlee的潇洒人生。
关注了也不一定更新，更新就不得了了。
精通SpringBoot——第九篇：整合Swagger在线文档

上一篇：精通SpringBoot——第三篇：详解WebMvcConfigurer接口


下一篇：精通SpringBoot——第一篇：DispatcherServlet和Multipart配置