springboot与Swagger集成

springboot与Swagger集成

1. 认识swagger

主要作用是为了前后端分离

1.1 概念

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步（来自百度）

1.2 特点

• 目前最流行的API框架
• RESTful api文档的在线生成工具 ==》API文档与API定义保持同步
• 直接运行，在线进行接口测试
• 支持多种语言

2. java项目中使用swagger-前提

依赖的话，一般都是jar文件。swagger也不例外，到maven仓库下载即可

在项目中使用swagger需要springfox;

     -  swagger2
     -  ui

3. springboot集成swagger

3.1 新建项目

新建一个springboot web项目（我是使用idea创建，当然也可以通过官网创建，原理相同）

我使用的是gradle创建（maven也是可以的）；

3.2 导入相关依赖

// https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
// https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

3.3 最简单的demo演示

其实，这样就可以了，只需要在springboot启动类上，加上一个开启swagger的注解，就可以访问ui页面

话不多说，先上图吧！

• 开启swagger

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

}

• hello world

@RestController
public class hello {
    @GetMapping("/hello")
    public String hello() {
        return "hello world";
    }
}

• 访问ui页面

一个最简单的swagger页面就产生了

localhost:8080/swagger-ui.html

4. 配置swagger

我们需要对swagger配置信息重新配置，来覆盖默认的配置信息。

首先创建一个swagger的配置类 SwaggerConfig

使用springboot配置注解以及开启swagger注解(开启此配置文件的话，会覆盖SwaggerdemoApplication的swagger注解)

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public  Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    public static final Contact CONTACT = new Contact(
            "小猿帅大人",
            "xiaoyuanshuai.com",
            "swagger@xiaoyuanshuai.com.cn");
    
    public ApiInfo apiInfo(){
        return new ApiInfo(
                "Swagger API文档",
                "这是swagger api文档的演示项目",
                "1.0",
                "urn:tos",
                CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<VendorExtension>());
    }
}

5. 配置扫描接口以及开关

在上述的接口中，不难发现有一个接口base-erro-controller这个接口，不是我写的。但却被swagger扫描到了。

前面也说了，在不配置任何信息的情况下，使用的是默认配置。我们可以根据自己实现的docket实例，覆盖这些选项。改成我们自己需要的swagger api文档的样子。

说白了就是逐渐完善docket实例的过程。为它增加有参构造函数，给方法复制的过程。感兴趣的话，下去可以自己阅读源码。进行更多配置。

下面介绍docket对象的一个方法-select()

使用**select()**方法有多种，建议阅读源码自行选择

这里配置了以扫描包的形式，确定哪些接口展示在swagger-ui里

    @Bean   
    public  Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
              .apis(RequestHandlerSelectors.basePackage("com.ws.swaggerdemo.controller"))
                .build();
    }

配置扫描接口也有多种方式

• 通过类的注解
• 通过方法的注解

6 分组以及接口常用注解

6.1 分组

可以看到我上面接口，有一个标注，是分组信息。大概能知道，swagger是有分组功能。每个docket实例中都有一个groupname,因此，多个分组可以写多个docket实例。

    @Bean
    public  Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("new group")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ws.swaggerdemo.controller"))
                .build();
    }
    @Bean
    public  Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("one group")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ws.swaggerdemo.controller"))
                .build();
    }
    @Bean
    public  Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("two group")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.ws.swaggerdemo.controller"))
                .build();
    }

效果图：

6.2 常用注解

当我们给具体的接口添加自己的信息时，就需要为，类，方法，字段，参数等添加注解。

接口注解

• @Api：用在请求的类上，表示对类的说明 tags=“说明该类的作用，可以在UI界面上看到的注解”

• @ApiOperation：描述方法的注解，用来描述方法的用途、作用 。value=“说明方法的用途、作用” notes=“方法的备注说明”， 可以点击查阅源码自行，思考有哪些参数

• @ApiImplicitParams：用在请求的方法上，表示一组参数说明

• @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 name：参数名 value：参数的汉字说明、解释 required：参数是否必须传 paramType：参数类型

@Api(value = "类描述",tags = {"hello demo功能"})
@RestController
public class hello {
    @ApiOperation(value = "返回用户 hello",notes = "方法的具体描述信息")
    @ApiImplicitParams({@ApiImplicitParam(name ="des",value = "描述", paramType = "String"),
                        @ApiImplicitParam(name ="name",value = "用户名", paramType = "String",required = true),
                        @ApiImplicitParam(name ="passworld",value = "密码", paramType = "String",required = true)})
    @GetMapping("hello2")
    public User hello2(String des,String name, String passworld){
        return  new User();
    }
}

效果

实体类注解

• @ApiModel：用在实体类上的注释（实体类被ui页面显示的条件是，定义的扫描接口中返回了该实体类）

• @ApiModelProperty：用在实体类的字段属性的注释

  @ApiModel(value = "user实体类")
  public class User {
  
      @ApiModelProperty(value = "用户名称",required = true)
      public String name;
  
      @ApiModelProperty(value = "用户密码",required = true)
      public String passworld;
  
      @ApiModelProperty(value = "用户描述")
      public String des;
  }
  

  效果
  

7 小结

综上基本可以上手swagger,大概介绍那么多，我们也能发现。swagger那么多注解，其实本身对代码逻辑没有半点影响。

这样做的好处，就是能有方便协同开发，提升效率等等。也可以方便测试。点击try it out进行测试。功能可比postman。