springboot集成swagger2

1. 关于Swagger

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

相信采用 Spring Boot 开发的小伙伴几乎是用来构建 RESTful API ，而文档自然是不可缺少的一部分，Swagger 的出现，既可以减少我们创建文档的工作量，同时说明内容又整合入实现代码中，让维护文档和修改代码整合为一体，可以让我们在修改代码逻辑的同时方便的修改文档说明。

另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。

作用总结：

• 接口文档在线生成
• 方便功能测试

集成后的效果图如下：

2. 开始集成

2.1 添加依赖

在 pom.xml 中添加 swagger 依赖

<!-- Swagger API文档 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>

2.2 配置Swagger

applicaton.yml

# Swagger界面内容配置
swagger:
  title: TMax API接口文档
  description: TMax Api Documentation
  version: 1.0.0
  termsOfServiceUrl: https://www.sscai.club
  contact:
    name: niceyoo
    url: https://www.sscai.club
    email: apkdream@163.com

如上配置请置于根节点，如下图所示：

Swagger2Config.java

新建一个 Swagger2Config.java 的配置类：

1. 添加 @Configuration 注解，用于定义配置类，方便被Spring Boot配置；
2. 添加 @EnableSwagger2 注解启动 Swagger 文档构建能力。

完整代码如下：

@Slf4j
@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Value("${swagger.title}")
    private String title;

    @Value("${swagger.description}")
    private String description;

    @Value("${swagger.version}")
    private String version;

    @Value("${swagger.termsOfServiceUrl}")
    private String termsOfServiceUrl;

    @Value("${swagger.contact.name}")
    private String name;

    @Value("${swagger.contact.url}")
    private String url;

    @Value("${swagger.contact.email}")
    private String email;

    private List<ApiKey> securitySchemes() {
        List<ApiKey> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("Authorization", "accessToken", "header"));
        return apiKeys;
    }

    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex("^(?!auth).*$")).build());
        return securityContexts;
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }

    @Bean
    public Docket createRestApi() {

        log.info("加载Swagger2");

        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo()).select()
            ## 扫描所有有注解的api，用这种方式更灵活
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .contact(new Contact(name, url, email))
                .version(version)
                .build();
    }
}

方法讲解：

通过 createRestfulApiDocs() 方法创建 Docket 的 Bean 之后，apiInfo() 用来创建该 API 的基本信息。（这些基本信息会展现在文档页面中，如最开始的预览图，增加一些文档自定义信息）

select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给Swagger 来展现，本例采用扫描所有带有 API 注解的对外开放，同时，你也可以采用指定扫描的包路径来定义，Swagger 则会扫描该包下所有 Controller定义的 API，并产生文档内容（除了被@ApiIgnore指定的请求）。

如果采用扫描指定包路径的话，需要修改 createRestApi() 方法的 apis 部分：

.apis(RequestHandlerSelectors.basePackage("com.lemon.security.web.controller"))

2.3 新建entity和controller测试

entity：VideoCategory.java

@Data
@Entity
@Table(name = "v_category")
@TableName("v_category")
@ApiModel(value = "视频类型")
public class VideoCategory extends TmaxBaseEntity {

    private static final long serialVersionUID = 1L;

    @ApiModelProperty(value = "类型名称")
    private String title;

    @ApiModelProperty(value = "排序值")
    @Column(precision = 10, scale = 2)
    private BigDecimal sortOrder;

    @ApiModelProperty(value = "是否启用 0启用 -1禁用")
    private Integer status = CommonConstant.STATUS_NORMAL;

}

controller：VideoCategoryController 主要以添加、查询为例

@Slf4j
@RestController
@Api(description = "视频类型管理接口")
@RequestMapping("/tmax/videoCategory")
@Transactional
public class VideoCategoryController extends TmaxBaseController<VideoCategory, String> {

    @Autowired
    private VideoCategoryService videoCategoryService;

    @Override
    public VideoCategoryService getService() {
        return videoCategoryService;
    }

    @RequestMapping(value = "/add", method = RequestMethod.POST)
    @ApiOperation(value = "添加")
    public Result<Object> add(@ModelAttribute VideoCategory videoCategory){

        VideoCategory d = videoCategoryService.save(videoCategory);
        return new ResultUtil<Object>().setSuccessMsg("添加成功");
    }

    @RequestMapping(value = "/search", method = RequestMethod.GET)
    @ApiOperation(value = "分类名模糊搜索")
    public Result<List<VideoCategory>> searchByTitle(
            @RequestParam String title,
            @ApiParam("是否开始数据权限过滤") @RequestParam(required = false, defaultValue = "true") Boolean openDataFilter){

        List<VideoCategory> list = videoCategoryService.findByTitleLikeOrderBySortOrder("%"+title+"%", openDataFilter);
        return new ResultUtil<List<VideoCategory>>().setData(list);
    }

}

常用注解说明：

• @Api()用于类；
  表示标识这个类是swagger的资源
• @ApiOperation()用于方法；
  表示一个http请求的操作
• @ApiParam()用于方法，参数，字段说明；
  表示对参数的添加元数据（说明或是否必填等）
• @ApiModel()用于类
  表示对类进行说明，用于参数用实体类接收
• @ApiModelProperty()用于方法，字段
  表示对model属性的说明或者数据操作更改
• @ApiIgnore()用于类，方法，方法参数
  表示这个方法或者类被忽略
• @ApiImplicitParam() 用于方法
  表示单独的请求参数
• @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

项目启动后访问：http://localhost:端口号(例如8080)/swagger-ui.html

我们尝试操作一下 add() 方法：

1. 填写实体基本信息
2. 点击 Try it out! 按钮

3. 最后

在上边的整个过程中，我们了解 Swagger 除了查看接口功能外，还提供了调试测试功能，点击“Try it out！”按钮，即可完成了一次请求调用！

此时，你也可以通过几个 POST 请求来验证之前的 POST 请求是否正确。相比为这些接口编写文档的工作，我们增加的配置内容是非常少而且精简的，对于原有代码的侵入也在忍受范围之内。

因此，在构建 RESTful API 的同时，加入 Swagger 来对 API 文档进行管理，是个不错的选择。

转载于:https://www.cnblogs.com/niceyoo/p/10959891.html