SpringBoot整合Swagger3.x 丝袜哥+常用注解

程序媛刘玲玲_HelloWorld
1,295 阅读4分钟

SpringBoot整合Swagger3.x 丝袜哥+常用注解

  • Swagger 丝袜哥

    • 简介：在java代码里面增加注解生成接口文档

      • 在代码里面增加注解
      RestController
@RequestMapping("api/v1/user")
@Api(tags = "用户模块",value = "用户UserController")
public class UserController {

    @Autowired
    private BannerService bannerService;

    @ApiOperation("分页用户列表")
    @GetMapping("list")
    public JsonData list(){

        List<BannerDO> list = bannerService.list();

        return JsonData.buildSuccess(list);
    }
}

    • 优点

      • 支持SpringMVC、SpringBoot、SpringCloud等主流java框架
      • 对java代码友好
      • 界面简洁
      • 国内比较活跃,主要是spring社区带动
      • 功能比较多

    • 缺点

      • 对跨语言支持不友好（可以和knife4j整合解决这个问题）
      • 代码需要引入相关依赖包和配置
      • 文档相对缺少

Swagger3.x常用注解讲解和配置

  • 用户模块相关接口文档配置
  • @Api 模块配置，用在controller类，描述API接口
    @Api(tags = "用户模块",value = "用户UserController")
    public class UserController {
    }
  • @ApiOperation 接口配置，用在方法上，描述接口方法
    @ApiOperation("分页用户列表")
    @GetMapping("list")
    public JsonData list(){

        return JsonData.buildSuccess();
    }
  • @ApiParam 方法参数配置，用在入参上面，描述参数
    @ApiOperation("用户登录")
    @PostMapping("login")
    public JsonData login(
            @ApiParam(name = "phone", value = "手机号",example = "13888888888")
            @RequestParam("phone") String phone,

            @ApiParam(name = "pwd", value = "密码",example = "123456")
            @RequestParam("pwd")String pwd){

        return JsonData.buildSuccess();
    }
  • restful例子
    @ApiOperation("删除用户")
    @DeleteMapping("/delete/{id}")
    public JsonData  deleteById(@PathVariable int id) {
        return JsonData.buildSuccess();
    }
  • @ApiIgnore 忽略此接口不生成文档
    @ApiIgnore
    @ApiOperation("删除用户")
    @DeleteMapping("/delete/{id}")
    public JsonData  deleteById(@PathVariable int id) {
        return JsonData.buildSuccess();
    }

简介：SpringFox和自动化接口文档生成工具Swagger介绍

  • Swagger介绍

    • 基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源接口文档自动生成工具，可以让开发人员快速设计、构建、记录以及使用 Rest API

    • 版本的说明

      • 目前的版本有swagger2.0和3.0

        • swagger2于17年停止维护，现在最新的版本为17年发布的 Swagger3（Open Api3）。

         

      • Swagger 主要包含了以下三个部分：

        • Swagger Editor：基于浏览器的编辑器，我们可以使用它编写我们 OpenAPI 规范。
        • Swagger UI：它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档，后文我将使用浏览器来查看并且操作我们的 Rest API。
        • Swagger Codegen：它可以通过为 OpenAPI（以前称为 Swagger）规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。

     

  • SpringFox介绍（是 spring 社区维护的一个非官方项目）

    • 是一个开源的API Doc的框架，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。官方定义为： Automated JSON API documentation for API's built with Spring。

    • 地址：github.com/springfox/s…

    • 版本的说明

      • SpringFox 3.0.0 发布（突破性的变更版本）
      • Spring5，Webflux支持，依赖少
      • 支持OpenApi 3.0.3
      • 有springboot的整合的starter，使用更便捷

实战新版Springboot2.x整合Swagger3.x

1. 添加依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2. 配置文件

#spring.application.name=xd_shop接口,增加中文会乱码，可以修改文件编码，或者使用yml格式
spring.application.name=xd_shop
# ===== 自定义swagger配置 ===== #
swagger.enable=true
swagger.application-name= ${spring.application.name}
swagger.application-version=1.0
#swagger.application-description=xd_shop电商平台管理后端接口文档
swagger.application-description=xd_shop api info

3. 配置类

package com.lzh.xd_shop.config;

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Component
@EnableOpenApi
@ConfigurationProperties("swagger")
@Data
public class SwaggerConfiguration{

    // 丝袜哥地址：http://localhost:端口/swagger-ui/index.html
    /**
     * 是否开启swagger，生产环境一般关闭，所以这里定义一个变量
     */
    private Boolean enable;

    /**
     * 项目应用名
     */
    private String applicationName;

    /**
     * 项目版本信息
     */
    private String applicationVersion;

    /**
     * 项目描述信息
     */
    private String applicationDescription;

  
   
     @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")

                // 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭
                .enable(enable)

                //配置api文档元信息
                .apiInfo(apiInfo())

                // 选择哪些接口作为swagger的doc发布
                .select()

                //apis() 控制哪些接口暴露给swagger，
                // RequestHandlerSelectors.any() 所有都暴露
                // RequestHandlerSelectors.basePackage("net.xdclass.*")  指定包位置
                // withMethodAnnotation(ApiOperation.class)标记有这个注解 ApiOperation
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

                .paths(PathSelectors.any())

                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                .contact(new Contact("CANCAT", "https://www.cuikaiyang.com", "1270038@qq.com"))
                .version(applicationVersion)
                .build();
    }
    
  }

4. 启动项目，访问浏览器

http://localhost:8081/swagger-ui/index.html

注意：如果访问不成功，记得看是否有拦截器拦截了相关资源，配置不拦截即可

image.png

5. 新建xxxController接口

package com.lzh.xd_shop.controller;

import com.lzh.xd_shop.model.BannerDO;
import com.lzh.xd_shop.service.BannerService;
import com.lzh.xd_shop.utils.JsonData;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.List;

/**
 * @Author：kaiyang.cui
 * @Package：com.lzh.xd_shop.controller
 * @Project：xd_shop
 * @name：BannerController
 * @Date：2023/4/1 下午3:56
 * @Filename：BannerController
 * @Description：BannerController
 * @Version：1.0
 */
@RestController
@RequestMapping("/api/v1/banner")
@Api(tags = "轮播图模块",value = "轮播图BannerController")
public class BannerController {

    @Autowired
    private BannerService bannerService;


    @RequestMapping("/listAllBanner")
    public JsonData listAllBanner(){
        List<BannerDO> list = bannerService.listAllBanner();

        return JsonData.buildSuccess(list );
    }

    @RequestMapping("/getAllbannerInfo")
    public JsonData getAllbannerInfo(){
        List<BannerDO> list = bannerService.getAllbannerInfo();

        return JsonData.buildSuccess(list );
    }


    @GetMapping("/list")
    @ApiOperation("轮播图列表")
    public JsonData list(){
        BannerDO banner1 = BannerDO.builder().img("img1.cuikaiyang.com").url("www1.cuikaiyang.com").weight(100).build();
        BannerDO banner2 = BannerDO.builder().img("img2.cuikaiyang.com").url("www2.cuikaiyang.com").weight(99).build();
        List list = new ArrayList();
        list.add(banner1);
        list.add(banner2);
        return JsonData.buildSuccess(list);
    }
}

http://localhost:8081/api/v1/banner/list

image.png

丝袜哥界面：

image.png

avatar
文章
阅读
粉丝