精通Spring Boot:整合Swagger在线文档

内容目录

在现代的软件开发中，API文档的编写和维护是非常重要的。因为它不仅可以帮助开发人员更快地理解和使用API，还可以提高代码的可读性和可维护性。Swagger是一个流行的API文档工具，Spring Boot是一个流行的Java Web框架。本文将介绍如何使用Springboot继承Swagger来创建和维护API文档。

开发中最烦的一件事是什么？当你全心全意思考的时候，前端笑眯眯的过来了：“大哥，你没告诉我该传什么参数！”……然后一堆吧啦吧啦扯淡，好了，前端大佬心满意足的走了，你以为事情也就这么结束了。滴滴滴，微信消息来了：“接口怎么不通啊，你是不是代码写的有问题啊？”一顿操作后，登上控制台，日志一看。

啊\~（我们一起学土拨鼠叫）内心是崩溃的… 参数少了，参数类型不对，格式不对，各种。这时候很想丢个文档给前端：你自己看吧！(我还是喜欢摸鱼看看美女图)

然而，写文档真的太麻烦了，懒…只好去逛逛论坛，百度谷歌下有没有什么生成在线文档的工具了，结果如你所愿，还真有。

今儿个，咱们就来走一波spring boot 整合 swagger 生成在线文档。（呼\~~爽，感觉用了这个，就可以不用被前端大佬“骚扰”了）。

介绍两种集成swagger的方式，越用越爽。写文档的时候可以用来和基友尬聊了（编程五分钟，扯淡两小时，一天就这么没了…）

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

2.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);
    }
}

2.1配置示例：

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

2.2配置说明–默认配置

- 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

2.3Path设置

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来排除所有监控端点。

2.4分组配置

- 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。

3.总结

上一篇：精通Spring Boot:整合RabbitMQ消息队列

本文介绍了如何使用Swagger来创建和维护API文档，并将其与Spring Boot集成起来。我们首先介绍了Swagger和Spring Boot的概念和背景，然后提供了一个基本的示例，演示如何在Spring Boot应用程序中添加Swagger依赖项，配置Swagger UI和生成API文档。

除此之外，我们还可以使用一些高级特性，例如如何添加自定义注释和扩展Swagger以支持其他格式。

最后，我们总结了Spring Boot整合Swagger的优点和缺点，并提供了封装好的swagger-starter，以帮助开发人员更好地使用Swagger和Spring Boot来开发Web应用程序。

最后，以上示例代码可在我的github.com-swagger-starter以及github.com-swagger及中找到。