jeesite如何配置swagger_5分钟搞定swagger集成和应用

Restful API 是当前流行的API规范，API文档编写是一件很重要的事情，也是一件很头疼的事情，Swagger 为我们提供了一套通过代码和注解自动生成文档的方法，有效缓解编写文档的痛苦和提高文档的及时性。

本文将使用 Swagger 2 规范的 Springfox 实现来了解如何在 Spring Boot 项目中使用 Swagger，主要包含了如何集成和使用Swagger 自动生成文档。

集成swagger

添加依赖

io.springfox    springfox-swagger2    2.9.2

增加配置类

Springfox 提供了一个 Docket 对象，让我们可以灵活的配置 Swagger 的各项属性。下面我们新建一个SwaggerConfig.java 类，并增加如下内容:

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket getDocket() {        return new Docket(DocumentationType.SWAGGER_2)                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build();    }}

注意: @Configuration 是告诉 Spring Boot 需要加载这个配置类，@EnableSwagger2 是启用 Swagger2，如果没加的话自然而然也就看不到后面的验证效果了。

验证

地址：http://localhost:8081/test/v2/api-docs

浏览器中输入上述地址会返回json格式数据，swagger集成完成，如果需要可视化展示则需要集成swagger ui，集成方式如下。

集成swagger ui

添加依赖

io.springfox    springfox-swagger-ui    2.9.2

验证

验证地址：http://localhost:8081/test/swagger-ui.html

浏览器输入上述地址，即可正常访问。至此swagger ui集成完成。

swagger ui页面

使用

1、给接口增加标签信息

通过在控制器类上增加@Api 注解，可以给接口增加标签信息。

package com.example.demo.controller;import com.example.demo.model.User;import io.swagger.annotations.Api;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.bind.annotation.RequestMethod;import org.springframework.web.bind.annotation.RestController;import java.util.ArrayList;import java.util.List;@Api(tags = "用户信息接口")@RestController@RequestMapping("/user")public class UserInfoController {    @ApiOperation("query users info")    @RequestMapping(value="/info",method= RequestMethod.GET)    public List queryUsersInfo(){        User user1 = new User();        user1.setAge(18);        user1.setName("Tom");        User user2 = new User();        user2.setAge(19);        user2.setName("Tomas");        List list = new ArrayList<>();        list.add(user1);        list.add(user2);        return list;    }}

2、添加接口的描述

通过在接口方法上增加 @ApiOperation 注解来展开对接口的描述，代码示例同上。增加接口标签和描述信息后，展示如下所示。

接口展示和请求实例

3、添加实体描述

可以通过 @ApiModel 和 @ApiModelProperty 注解来对我们 API 中所涉及到的对象做描述。

package com.example.demo.model;import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty;@ApiModel("用户实体")public class User {    @ApiModelProperty("姓名")    private String name;    @ApiModelProperty("年龄")    private int age;    public String getName() {        return name;    }    public void setName(String name) {        this.name = name;    }    public int getAge() {        return age;    }    public void setAge(int age) {        this.age = age;    }}

对应model视图如下：

model展示

4、接口过滤

Swagger2 提供给我们了两种方式配置，一种是基于 @ApiIgnore 注解，另一种是在 Docket 上增加筛选。Docket 类提供了 apis() 和 paths()两 个方法来帮助我们在不同级别上过滤接口：

• apis()：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描。

• paths()：这种方式可以通过筛选 API 的 url 来进行过滤。

生产环境关闭swagger

1、在application.properties文件中增加

#是否激活 swagger true or falseswagger.is.enable=false

2、在swagger配置类Docket中增加enable(swagger_is_enable)

@Configuration@EnableSwagger2public class SwaggerConfig {    @Value("${swagger.is.enable}")    private boolean swagger_is_enable;    @Bean    public Docket getDocket() {        return new Docket(DocumentationType.SWAGGER_2)                .enable(swagger_is_enable)                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build();    }}

可以通过各环境的application.properties中的swagger.is.enable配置项控制swagger功能的开启和关闭。