Swagger UI 在Spring boot中的应用

原创

leaforbook

修改于 2019-03-01 11:54:12

1.9K0

修改于 2019-03-01 11:54:12

文章被收录于专栏：Spring CloudSpring Cloud

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接口，并生成文档。