Spring boot 使用 Swagger3 生成API接口文档

简介: 本文是Swagger3 相关笔记总结,方便自己以后复习,同时也希望对大家有所帮助。

本文是Swagger3 相关笔记总结,方便自己以后复习,同时也希望对大家有所帮助。

一、导入依赖

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

二、编写相关类

1.application.yml

server:
  port: 8089

spring:
  application:
    name: bbx-swagger
  # ===== 避免spring boot版本和swagger版本不一致报错 ===== #
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

# ===== 自定义swagger配置 ===== #
swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: v1.0
  application-description: springfox swagger 3.0 Demo
  try-host: http://localhost:${server.port}

2.SwaggerProperties 类

@Component
@ConfigurationProperties("swagger")
@Data
public class SwaggerProperties {

    /**
     * 是否开启swagger,生产环境一般关闭,所以这里定义一个变量
     */
    private Boolean enable;

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

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

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

    /**
     * 接口调试地址
     */
    private String tryHost;
}

3.Swagger配置类

@Configuration
@EnableOpenApi //swagger3启动注释
public class SwaggerConfig {
    @Autowired
    private SwaggerProperties swaggerProperties;

    @Bean
    public Docket userDocket(){
        return new Docket(DocumentationType.OAS_30)
                //定义是否开启swagger
                .enable(swaggerProperties.getEnable())
                .groupName("bbx")
                //api展示信息
                .apiInfo(apiInfo())
                //接口调试地址
                .host(swaggerProperties.getTryHost())
                //过滤条件
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bbx.swagger.controller"))
                .build();
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                //定义是否开启swagger
                .enable(swaggerProperties.getEnable())
                .groupName("fft");
    }

    private ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("bbx","https://blog.csdn.net/BBQ__ZXB?type=blog","1101249732@qq.com");
        return new ApiInfo(
                swaggerProperties.getApplicationName() + "APi Doc",
                swaggerProperties.getApplicationDescription(),
                swaggerProperties.getApplicationVersion(),
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

4. Controller

@RestController
@RequestMapping("/user")
@Api(tags = "用户接口类")
//@Tag(name = "用户管理", description = "用户数据增删改查") 不生效
public class UserController {

    @Autowired
    private UserService userService;


    @ApiOperation("测试接口1") //swagger2
    //@Operation(summary = "测试接口1") //swagger3
    @PostMapping("/show1")
    public String show1(@ApiParam(value = "姓名", required = true, example = "笨笨熊")@RequestBody String name) {
        return "hello," + name;
    }

    @ApiOperation("测试接口2")
    @PostMapping("/show2")
    public String show2(@ApiParam(value = "用户对象", required = true) @RequestBody User user) {
        return "hi," + user.getName();
    }
}

5. 实体类User

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel("用户实体类")
//@Schema(name = "用户实体类") 不生效
public class User {

    //swagger3
    @Schema(description = "姓名",required = true,example = "笨笨熊")
    private String name;
    
    //swagger2
    @ApiModelProperty(value = "年龄",required = true,example = "21")
    private Integer age;
}

6. 常用注解

swagger3的注解与swagger2相差很多,但兼容了swagger2的注解,区别如下:
在这里插入图片描述

三、Swagger管理页面

http://localhost:8089/swagger-ui/index.html
在这里插入图片描述
在这里插入图片描述


四、使用knife4j优化体验

1. 导入依赖

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

2. 访问网址

http://localhost:8089/doc.html

在这里插入图片描述


参考博客:
Swagger3 注解使用(Open API 3)

目录
相关文章
|
2天前
|
前端开发 Java 程序员
Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2
|
4天前
|
IDE Java API
如何使用Java和Spring Boot来开发一个基本的RESTful API
如何使用Java和Spring Boot来开发一个基本的RESTful API
10 0
|
8天前
|
负载均衡 Java API
Spring Cloud Gateway 详解:构建高效的API网关解决方案
Spring Cloud Gateway 详解:构建高效的API网关解决方案
16 0
|
10天前
|
Java API 网络架构
【Spring Boot】详解restful api
【Spring Boot】详解restful api
17 0
|
12天前
|
Java API 开发者
Java一分钟之-Spring Cloud Gateway:API网关
【6月更文挑战第10天】Spring Cloud Gateway是Spring Cloud生态中的API网关组件,基于Spring Framework 5、Reactor和Spring Boot 2.0,支持响应式编程。它提供路由转发、过滤器链(包括预处理、路由和后处理)和断言功能。快速入门涉及添加相关依赖和配置路由规则。常见问题包括路由冲突、过滤器顺序和性能瓶颈。通过动态路由和过滤器示例,展示了其灵活性。Spring Cloud Gateway是微服务架构的有力工具,可提升系统稳定性和开发效率。
132 0
|
15天前
|
XML 前端开发 Java
Spring3 MVC中使用Swagger生成API文档
Spring3 MVC中使用Swagger生成API文档
16 0
|
Web App开发 测试技术 API
Spring-Boot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。
2157 0
|
3天前
|
XML 安全 API
API攻防-接口安全&SOAP&OpenAPI&RESTful&分类特征导入&项目联动检测
API攻防-接口安全&SOAP&OpenAPI&RESTful&分类特征导入&项目联动检测
|
1天前
|
Java API
java调用个人微信API接口收发朋友圈,删除评论朋友圈
java调用个人微信API接口收发朋友圈,删除评论朋友圈
|
1天前
|
安全 API 网络安全
API接口安全加固:应对黑客攻击的实战指南
**API安全摘要:** API成为黑客目标,攻击类型包括未授权访问、CSRF、DDoS、数据泄露和注入攻击。防御策略包括使用OAuth 2.0和JWT进行认证授权,防止CSRF攻击,限制请求速率,避免数据泄露,以及实施注入攻击防护。开发者应定期更新安全措施,确保API安全性。示例代码展示了Node.js中JWT认证的实现。