swagger

swagger

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

• 号称世界上最流行的Api框架

• RestFul Api文档在线自动生成工具=》Api文档与Api定义同步更新

• 直接运行，可以在线测试API接口

• 支持多种语言

作用：

1.接口的文档在线自动生成。

2.功能测试。

 

在项目中使用Swagger需要springbox；

• swagger2

• ui

Springboot集成Swagger

1. 新建Springboot项目

2. 导入相关依赖

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

3. 编写一个hello项目

4. 配置Swagger==》Config

   @Configuration
   @EnableSwagger2  //开启Swagger2
   public class SwaggerConfig {
       
   }
   ​

5. 测试运行： http://localhost:8080/swagger-ui.html

 

配置Swagger

Swagger的bean实例Docket；

SwaggerConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
​
import java.util.ArrayList;
​
@Configuration
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
​
​
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
​
    //配置Swagger信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("", "", "");
        return new ApiInfo(
                "aaa",
                "你好",
                "1.0",
                "urn:tos",
                 contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}
​

运行访问

 Swagger配置扫描接口

Docket.select()

SwaggerConfig.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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;
​
import java.util.ArrayList;
​
@Configuration
    @EnableSwagger2  //开启Swagger2
    public class SwaggerConfig {
​
​
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //RequestHandlerSelectors,配置要扫描接口的方式
                    //basePackage:指定要扫描的包
                    //any():扫描全部
                    //none():不扫描
                    //withClassAnnotation():扫描类上的注解，参数是一个注解的反射对象
                    //withMethodAnnotation():扫描方法上的注解
                    //.apis(RequestHandlerSelectors.withClassAnnotation(Controller.class))
                    //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                    .apis(RequestHandlerSelectors.basePackage("com.bxb.swagger.controller"))
                    //paths():过滤什么路径:值扫描/bxb/下面的接口
                    .paths(PathSelectors.ant("/bxb/**"))
                    .build();
        }
​
}

配置是否启动Swagger

 public class SwaggerConfig {
​
        //配置了Swagger的Docket的bean实例
        @Bean
        public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(false);//enable是否启动Swagger，如果为false，则Swagger不能再浏览器访问

 

如果我只希望我的Swagger在生产环境中使用，在发布的时候不用；

• 判断是不是生产环境 flag

• enable注入（flag）

@Configuration
@EnableSwagger2  //开启Swagger2
public class SwaggerConfig {
​
        //配置了Swagger的Docket的bean实例
        @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(flag);//enable是否启动Swagger，如果为false，则Swagger不能再浏览器访问

application.properties

spring.profiles.active=dev

application-dev.properties

server.port=8081

application-pro.properties

server.port=8082

因为 Profiles profiles = Profiles.of("dev", "test");指定了“dev”和“test”环境；

这样使用8081端口访问就可以访问，8082端口不能访问；

 

配置API文档的分组

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

如何配置多个分组，多个Docker实例即可，可以实现多人协同开发

@Configuration
    @EnableSwagger2  //开启Swagger2
    public class SwaggerConfig {
​
        @Bean
        public Docket docket1(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("B");
        }
        @Bean
        public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
        }
        @Bean
        public Docket docket3(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("D");
        }
​
​
        //配置了Swagger的Docket的bean实例
        @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())
                    .groupName("A")
                    .enable(flag);//enable是否启动Swagger，如果为false，则Swagger不能再浏览器访问

分组显示

 

实体类注释

//@Api(注释)
//@ApiModel("用户实体类")
public class User{
    @ApiModelProperty("用户名")
    public String username;
     @ApiModelProperty("密码")
    public String password;
}
//@ApiModel：给实体类写注释
// @ApiModelProperty：给实体类属性写注释

controller

//@ApiOpertion("hello控制类")//Opertion接口，放在方法上，给方法添加注解
​
@Controller
public class helloController {
    @ApiOperation("hello控制类")
    @GetMapping(value = "/hello")
    @ResponseBody
    public String hello(){
        return  "hello";
    }
}

总结：

1. 可以通过Swagger给一些比较难理解的属性或者接口，增加注释信息，解决前后端分离集成联调时，前端人员和后端人员无法做到“及时协商”。

2. 接口文档实时更新

3. 可以在线测试

注意：在项目正式发布的时候关闭Swagger，安全，减少内存消耗；