Swagger UI 在Spring boot中的应用

Swagger UI是一个自动生成Java web接口文档的库。Swagger UI可以帮助前端开发者和后端开发者方便地进行沟通,后端开发者可以因此节省很多写接口文档的时间和精力,前端开发者也可以得到一个完备清晰的文档。

下面介绍如何在Spring boot应用中配置使用Swagger UI。


1.添加Maven依赖

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

2.给启动类配置注解

给Spring boot启动类加上@EnableSwagger2注解。

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

3.使用Java配置的形式配置Swagger2

import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfigure {

    @Value("${swagger.custom.base.package}")
    private String basePackage;

    @Value("${swagger.custom.title}")
    private String title;

    @Value("${swagger.custom.description}")
    private String description;

    @Value("${swagger.custom.url}")
    private String url;

    @Value("${swagger.custom.name}")
    private String name;

    @Value("${swagger.custom.email}")
    private String email;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(SwaggerConfigure.basePackage(basePackage))
                //.apis(RequestHandlerSelectors.basePackage("com.leaforbook.orange.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(url)
                .contact(new Contact(name,url,email))
                .version("1.0")
                .build();
    }


    /**
     * Predicate that matches RequestHandler with given base package name for the class of the handler method.
     * This predicate includes all request handlers matching the provided basePackage
     *
     * @param basePackage - base package of the classes
     * @return this
     */
    public static Predicate<RequestHandler> basePackage(final String basePackage) {
        return new Predicate<RequestHandler>() {

            @Override
            public boolean apply(RequestHandler input) {
                return declaringClass(input).transform(handlerPackage(basePackage)).or(true);
            }
        };
    }

    /**
     * 处理包路径配置规则,支持多路径扫描匹配以逗号隔开
     *
     * @param basePackage 扫描包路径
     * @return Function
     */
    private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
        return new Function<Class<?>, Boolean>() {

            @Override
            public Boolean apply(Class<?> input) {
                for (String strPackage : basePackage.split(",")) {
                    boolean isMatch = input.getPackage().getName().startsWith(strPackage);
                    if (isMatch) {
                        return true;
                    }
                }
                return false;
            }
        };
    }

    /**
     * @param input RequestHandler
     * @return Optional
     */
    private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
        return Optional.fromNullable(input.getClass());
    }


}

SwaggerConfigure可以作为一个公共类,放在任何Spring项目中。通过使用该类的项目的配置可以定制化展示接口页面。该类还实现了同时扫描多个包路径下的web接口,适应项目中在多个包路径下防止Controller类的情况。接下来就是要在Spring配置文件中配置该类中使用到的各个变量。

4.配置Swagger

#Swagger配置
swagger.custom.base.package=com.xxx.xxxx.controller
swagger.custom.title=xxx接口详情
swagger.custom.description=xxx接口详情
swagger.custom.url=www.xxx.com
swagger.custom.name=xxxx
swagger.custom.email=xxxx@xx.com

5.在Controller类中添加Swagger注解

import com.leaforbook.common.basic.BasicResponse;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/user/user")
@Slf4j
@Api(value = "用户信息维护", description = "用户信息维护")
public class UserController {

    @PostMapping("/create")
    @ApiOperation(value = "创建用户信息", notes = "")
    public BasicResponse create() {
        return null;
    }
}

@Api注解和@ApiOperation注解都是Swagger的注解,有了这两个注解,Swagger组件就会扫描到相应的web接口,并生成文档。

6.查看效果

启动项目后,假设是本地启动,项目的web端口是8080,访问http://127.0.0.1:8080/swagger-ui.html,就能看到接口文档:


有了这个工具,我们可以非常方便地进行前后端联调。本文通过分离出不变的配置过程和会变化的个性化展示和多包路径扫描,写了一个公共类,使Swagger得以非常方便地引入Spring boot项目。

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

编辑于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券