Swagger 简单快速入门教程

Posted 2022-07-20 爱学习的大鱼

一、使用 springfox生成接口UI

1、导入springfox-boot-starter依赖

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

2、配置config

@Configuration
@EnableOpenApi
@Slf4j
public  class SwaggerConfig extends WebMvcConfigurationSupport 

    /**
     * 设置静态资源映射
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) 
        log.info("开始进行静态资源映射....");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
    

    @Bean
    public Docket docket() 
        return new Docket(DocumentationType.OAS_30) // 选择文档类型 OpenApi 3.0
                .apiInfo(apiInfo()) //配置swagger信息
                .enable(true)  // 是否开启  默认开启;
                .groupName("reggie") // reggie
                .select() // 选择
                .apis(RequestHandlerSelectors.basePackage("com.xy.reggie.controller")) // 扫描的包路径下的类
                .build(); // 创建
    

    private ApiInfo apiInfo() 
        return new ApiInfo(
                "reggie 文档",
                "reggie 文档",
                "v1.0",
                "https://www.xxx.edu.cn/",
                new Contact("谢阳", "https://blog.51cto.com/learningfish", "[e-mail]"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    

3、swagger的Api介绍

姓名	描述
@Api	将类标记为 Swagger 资源（一般用于描述Controller）
@ApiImplicitParam	表示 API 操作中的单个参数 （一般用于描述具体方法参数）
@ApiImplicitParams	允许多个 ApiImplicitParam 对象列表的包装器（一般用于包裹@ApiImplicitParam）
@ApiModel	提供有关 Swagger 模型的其他信息 （一般用于描述Controller方法参数的pojo类）
@ApiModelProperty	添加和操作模型属性的数据（一般用于描述pojo的属性）
@ApiOperation	描述针对特定路径的操作或通常是 HTTP 方法。（一般用于描述Controller方法）
@ApiParam	为操作参数添加额外的元数据。
@ApiResponse	描述操作的可能响应。
@ApiResponses	允许多个 ApiResponse 对象列表的包装器。
@Authorization	声明要在资源或操作上使用的授权方案。
@AuthorizationScope	描述 OAuth2 授权范围。

• @Api用法如下:

@Slf4j
@RestController
@RequestMapping("/category")
@Api(tags = "分类相关接口")
public class CategoryController 

• @ApiOperation用法如下:

@ApiOperation("添加菜品")
@CacheEvict(value = "categoryCache",allEntries = true)
@PostMapping
public R<String> addCategory(@RequestBody Category category) 
    log.info("添加分类category", category);
    categoryService.save(category);
    return R.success("添加菜品分类成功");

• @ApiImplicitParams、@ApiImplicitParam用法如下:

@ApiOperation("请求分页")
@Cacheable(value = "categoryCache",key = "#pageNum + _ + #pageSize" )
@GetMapping("/page")
@ApiImplicitParams(
        @ApiImplicitParam(name = "page",value = "页码",required = true),
        @ApiImplicitParam(name = "pageSize",value = "每页记录数",required = true),
)
public R<Page> page(@RequestParam("page") Integer pageNum,
                    @RequestParam("pageSize") Integer pageSize) 
    log.info("category分类分页");
    Page<Category> categoryPageInfo = new Page<>(pageNum, pageSize);
    LambdaQueryWrapper<Category> queryWrapper = new LambdaQueryWrapper<>();
    queryWrapper.orderByAsc(Category::getSort);
    categoryService.page(categoryPageInfo, queryWrapper);
    return R.success(categoryPageInfo);

• @ApiModel、@ApiModelProperty用法如下:

@Data
@ApiModel("分类")
public class Category implements Serializable 

    private static final long serialVersionUID = 1L;

    @ApiModelProperty("主键")
    private Long id;

    //类型 1 菜品分类 2 套餐分类
    @ApiModelProperty("类型 1 菜品分类 2 套餐分类")
    private Integer type;

    //分类名称
    @ApiModelProperty("分类名称")
    private String name;

    //顺序
    @ApiModelProperty("顺序")
    private Integer sort;

访问swagger-ui/index.html接口：

https://localhost:8080/swagger-ui/index.html
http://localhost:8080/swagger-ui/index.html

二、使用knife4j生成接口UI

1、导入knife4j-spring-boot-starter依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2、配置config

@Configuration
@EnableOpenApi
@Slf4j
public  class SwaggerConfig extends WebMvcConfigurationSupport 

    /**
     * 设置静态资源映射
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) 
        log.info("开始进行静态资源映射....");
        registry.addResourceHandler("/backend/**").addResourceLocations("classpath:/backend/");
        registry.addResourceHandler("/front/**").addResourceLocations("classpath:/front/");
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    

    @Bean
    public Docket docket() 
        return new Docket(DocumentationType.OAS_30) // 选择文档类型 OpenApi 3.0
                .apiInfo(apiInfo()) //配置swagger信息
                .enable(true)  // 是否开启  默认开启;
                .groupName("reggie") // reggie
                .select() // 选择
                .apis(RequestHandlerSelectors.basePackage("com.xy.reggie.controller")) // 扫描的包路径下的类
                .build(); // 创建
    

    private ApiInfo apiInfo() 
        return new ApiInfo(
                "reggie 文档",
                "reggie 文档",
                "v1.0",
                "https://www.xxx.edu.cn/",
                new Contact("谢阳", "https://blog.51cto.com/learningfish", "[e-mail]"),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    

访问doc.html页面：

https://localhost:8080/doc.html#/home 
http://localhost:8080/doc.html#/home