Swagger 简单快速入门教程

一、使用 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", "xxxx@qq.com"), "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", "xxxx@qq.com"), "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