Spring Boot使用Swagger生成API手册

小咪咪 2022-05-26 12:30 82阅读 0赞

现在越来越多的应用都采用restful风格的开发模式来构建API，这样也有利于实现前后端分离，前端进行数据展示，后端提供数据，前后端之间通过json的格式来进行数据传递。这时候前后端之间的交流就只有通过API来进行了，但是随着发布的API越来越多交流与测试就成了一个很麻烦的事情。  
为了解决这类问题业界也提供各种解决方案，我们这里选用Swagger技术来解决这个问题，关于Swagger的介绍请参见官网[Swagger][]，当然Swagger提供了java实现，因为我采用的spring boot所以选用springfox这个开源实现来集成Swagger。  
软件环境

> spring boot 2.0

首先需要引入依赖，我们看pom文件

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.8.0</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.8.0</version>
            </dependency>

下一步我们就要创建Swagger的配置类，参见以下代码

/** * @author chengjian * @date 2018/2/19 **/
    
    @Configuration
    @EnableSwagger2 //Enable swagger 2.0 spec
    @ComponentScan(basePackageClasses = {
            UserController.class
    })
    public class SwaggerConfiguration extends WebMvcConfigurerAdapter { 
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
    
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
        @Bean
        public Docket userApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("user-api")
                    .apiInfo(apiInfo())
                    .select()
                    .paths(userPaths())
                    .build();
        }
        private Predicate<String> userPaths() {
            return regex("/user.*");
        }
        /** * api 页面简介 * * @return */
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("XXX系统API")
                    .description("提供相应的数据调用api，仅供测试")
                    .version("1.0")
                    .build();
        }
    
    }

代码很简单，当然这只是最简单的Swagger配置  
@EnableSwagger2 //Enable swagger 2.0 spec 这个注解说明我们采用的是最新的Swagger2版本  
@ComponentScan(basePackageClasses = \{UserController.class\}  
这个注解表明我们将UserController这个类纳入Swagger管理，如果有多个类要使用Swagger那么需要加入多个累并以逗号分隔。  
addResourceHandlers()这个方法是定义了Swagger页面的映射路径，如果不配置就没法跳转到相应的Swagger页面。  
userApi()和userPaths()方法就定义了UserController具体的配置信息。  
apiInfo()这个方法定义了Swagger相应的描述信息。  
这样我们就完成了Swagger的基础配置  
完成了Swagger的配置后我们需要定一个一个Controller来实现Swagger的跳转映射，因此我们创建了一个Controller

package com.spring.common.controller;
    
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.RequestMapping;
    
    @Controller
    public class HomeController {
        @RequestMapping("/")
        public String home() {
            System.out.println("homecontroller");
            return "redirect:swagger-ui.html";
        }
    }

这里我们就定义了Swagger的映射和跳转。

至此我们就完成了Swagger的基本使用，其实Swagger包含了很多的使用方法，例如安全之类的可以参见springfox的官方文档[springfox][]。  
这里的简单的配置我也有代码实现，可以参考我的代码[spring][]

[Swagger]: https://swagger.io/
[springfox]: http://springfox.github.io/springfox/docs/current/
[spring]: https://github.com/jackycheng86/spring