后端编写Swagger接口管理文档

Swagger接口管理文档

访问接口文档的网页：http://localhost:8080/swagger-ui/index.html

导入依赖

1. <dependency>
2.     <groupId>io.springfox</groupId>
3.     <artifactId>springfox-boot-starter</artifactId>
4.     <version>3.0.0</version>
5. </dependency>

复制代码

编写yaml

SpringBoot 2.6以上版本修改了路径匹配规则，但是Swagger3还不支持，这里换回之前的，不然启动直接报错

1. spring:
2.         mvc:
3.                 pathmatch:
4.       matching-strategy: ant_path_matcher

复制代码

创建配置类配置swagger信息

这个是配置swagger网页的大文字

1. @Configuration
2. public class SwaggerConfiguration {
3.     @Bean
4.     public Docket docket() {
5.         return new Docket(DocumentationType.OAS_30)
6.                 .apiInfo(apiInfoMyself())
7.                 .select()   //开启选择扫描接口功能
8.                 .apis(RequestHandlerSelectors.basePackage("com.example.controller"))    //设置swagger只扫描该包下的接口(还可以设置只扫描每个类，某个方法）
9.                 .build();
10.     }
12.     private ApiInfo apiInfoMyself(){
13.         return new ApiInfoBuilder()
14.                 .contact(new Contact("你的名字", "https://www.bilibili.com", "javastudy111*@163.com"))
15.                 .title("图书馆里系统——在线api接口文档")
16.                 .description("欢迎各位前端大佬前来访问接口")
17.                 .version("1.1") //自己随便定义这个接口第几版的
18.                 .build();
19.     }
20. }

复制代码

添加具体描述

1. //为xxxcontroller这个类加注解
2. @Api(tags = "账户验证接口", description = "包括用户登录、注册、验证码请求等操作。")
3. @RestController
4. @RequestMapping("/api/auth")
5. public class AuthApiController {
6.    
7. //为某个接口添加注解
8. @ApiResponses({
9.         @ApiResponse(code = 200, message = "邮件发送成功"),  
10.         @ApiResponse(code = 500, message = "邮件发送失败")   //不同返回状态码描述
11. })
12. @ApiOperation("请求邮件验证码")   //接口描述
13. @GetMapping("/verify-code")
14. public RestBean<Void> verifyCode(@ApiParam("邮箱地址") @RequestParam("email") String email,//请求参数的描述
15.                                 @ApiParam("邮箱地址") @RequestParam("email") String email){
16.    
17. //让swagger忽略每个接口
18. @ApiIgnore     //忽略此请求映射
19. @PostMapping("/login-success")
20. public RestBean<Void> loginSuccess(){
21.     return new RestBean<>(200, "登陆成功");
22. }
23.    
24. //为实体类添加描述（因为有时候会返回一个实体类，所以需要告诉前端人员这个实体类描述的是啥）
25. @Data
26. @ApiModel(description = "响应实体封装类")
27. @AllArgsConstructor
28. public class RestBean<T> {
30.     @ApiModelProperty("状态码")
31.     int code;
32.     @ApiModelProperty("状态码描述")
33.     String reason;
34.     @ApiModelProperty("数据实体")
35.     T data;
37.     public RestBean(int code, String reason) {
38.         this.code = code;
39.         this.reason = reason;
40.     }
41. }
42.    

复制代码

如果有配置多环境，prod生产环境就没必要开启swagger了

1. springfox:
2.   documentation:
3.     enabled: false

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！