springboot搭建restful网站学习篇（三）：Swagger

在开发restful api时，为了尽量规范接口、调试接口，同时能够提供一份详实的api文档出来，一般都会添加上Swagger组件。

1）修改pom.xml文件，添加依赖项

        <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）通过注解来配置Swagger

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ppl.aegis.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("AEGIS后台系统")
                .description("AEGIS后台模块")
                .version("1.0")
                .build();
    }
}

@Configuration用于定义配置类，可替换xml配置文件，被注解的类内部包含有一个或多个被@Bean注解的方法，这些方法将会被spring进行扫描，并用于将实例注入spring容器中。

@EnableSwagger2启用Swagger2

.apis(RequestHandlerSelectors.basePackage("com.ppl.aegis.controller"))该句需要指定到所要展示的controller文件路径。

增加配置类后，于controller类添加注解

@RestController
@Api(tags = "Test", description = "测试类")
@RequestMapping("/test")
public class Test {

    @ApiOperation("返回hello world")
    @RequestMapping(value = "/string",method = RequestMethod.GET)
    @ResponseBody
    public String GetString()
    {
        return "Hello World.";
    }
}

@Api及@ApiOperation即为swagger的注解，各注解用法请参考官网。

浏览器打开http://localhost:8080/swagger-ui.html，即可看到api相关信息。默认端口是8080.

Swagger-ui界面虽然能够展示api信息，但是在生产环境一般不能随意展示，因此需要增加配置，由配置决定是否开启。
1）于swagger配置类Swagger2Config 上增加注解

@Configuration
@EnableSwagger2
@Profile("dev")
public class Swagger2Config {

dev为标识，表示当当前环境为dev时，启用swagger页面

2）于项目配置文件中增加配置

spring:
  profiles:
    active: dev #默认为开发环境

通过修改active值即可开闭页面。我这里已经将application.properties改成了yml格式，所以properties格式需略作修改。

若不是dev环境，则将出现下面提示：

最后编辑于：2020.05.30 23:16:17