swagger入门

swagger

swagger Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的Web服务。

Swagger是一个流行的API开发框架，Swagger允许用户使用Swagger编辑器描述OAS 3.0 API（OpenAPI Specification，OAS），并使用Swagger UI可视化并自动生成OAS 3.0中定义的API文档。

Swagger 对整个API的开发周期都提供了相应的解决方案，是一个规范和完整的框架。包括API设计、API开发、API文档、API测试、API治理等，Swagger几乎支持所有语言。

导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

swagger配置扫描接口

Docket.select()

@Configuration
@EnableSwagger2 //开启swagger2
public class ConfigSwagger  { 
    	@Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors 配置要扫描接口的方式
                    //basePackage 指定要扫描的包
                    //any 扫描全部
                    //none 不扫描
                    //withClassAnnotation 扫描类上的注解，参数是一个注解的反射对象
                    //withMethodAnnotation 扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.guo.springbootswagger.controller"))
                    //path 过滤什么路径
                    //ant() 只扫描/guo/** 
                    .paths(PathSelectors.ant("/guo/**"))
                    .build();
        }
        //构建 api文档的详细信息函数
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //页面标题
                    .title("Spring Boot使用 Swagger2 构建RestFul API")
                    //创建人
                    .contact(new Contact("图图", "http://localhost:8080/swagger-ui.html", "sp.guo@qq.com"))
                    //版本号
                    .version("1.0")
                    //描述
                    .description("跑圈模块接口文档")
                    .build();
        }
}

配置是否启动swagger

    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // enable 是否启动swagger，如果false，则swagger不能在浏览器中访问
                .enable(false)
                //select 以下是一套
                .select()     
                .apis(RequestHandlerSelectors.basePackage("com.guo.springbootswagger.controller"))
                .build();
    }

如何让swagger只在生产环境使用？

判断是不是生产环境 flag = false

只需修改 默认配置文件 profiles.active = ..
-application.properties  (spring.profiles.active=dev)
-application-dev.properties (生产环境 端口 8080)
-application-pro.properties （ 端口 8081）

注入 enable（flag）

@Configuration
@EnableSwagger2 //开启swagger2
public class ConfigSwagger  {
    @Bean
    public Docket docket(Environment environment) {
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");
        //通过environment.acceptsProfiles判断是否出在自己设定的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // enable 是否启动swagger，如果false，则swagger不能在浏览器中访问
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.guo.springbootswagger.controller"))
                .build();
    }
    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot使用 Swagger2 构建RestFul API")
                //创建人
                .contact(new Contact("图图", "http://localhost:8080/swagger-ui.html", "sp.guo@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("跑圈模块接口文档")
                .build();
    }
}

配置API文档的分组

.groupNmame("A") 组名

如何配置多个分组；多个Docket实例即可

 @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }
    
    @Bean
    public Docket docket4(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("D");
    }

使用swagger进行测试

@Api(value = "User-API",description = "这是用户接口详细信息的描述")
@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
    
    //只要我们接口中返回值中存在实体类，他就会被扫描swagger
    @ApiOperation(value = "获取用户列表", notes = "根据url的id来获取用户详细信息，返回List<User>类型用户信息的JSON")
    @PostMapping(value = "/user")
    public User user(){

        return new User();
    }
}

总结

1、可以通过swagger给一些比较难理解的属性或者接口，增加注释信息

2、接口文档实时更新

3、可以在线测试