SpringBoot项目使用Swagger2接口工具

简介: 使用RESTful服务通常是涉及到多个终端的团队,比如Android、iOS、WEB等。为了让大家沟通顺畅,通常我们需要编写一份详细的RESTful业务接口文档

前言

使用RESTful服务通常是涉及到多个终端的团队,比如Android、iOS、WEB等。为了让大家沟通顺畅,通常我们需要编写一份详细的RESTful业务接口文档


使用Swagger2有助于我们编写一份详细的RESTful业务接口文档,过去经常会使用Word或者Excel,但是接口非常多,细节又复杂,如果由程序员高质量的输出一个文档,经常耗时长而且效果也不好。Swagger2能将代码和注释说明很好结合在一块。既减轻了研发人员的负担,又能输出高质量的文档。


下面说下如何去使用

pom.xml中添加Swagger2依赖

 <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

创建Swagger2配置类

@Configuration注解,让Spring来加载该类配置。
@EnableSwagger2注解来启用Swagger2。
apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。
RequestHandlerSelectors.basePackage()中填的是你controller的目录
apiInfo()方法中termsOfServiceUrl和contact可以用Contact的对象代替

注意:

Swagger2已经不支持String类型的contact

Contact对象中name表示作者,url通常作为项目的链接,代替之前的termsOfServiceUrl方法,email的话不用我多说了吧,不想写的话可以为空字符串屏幕截图 2023-08-28 204831.png

createRestApi函数创建Docket的Bean之后,apiInfo() 用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。


**select()**函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。

@Configuration
@EnableSwagger2
public class SwaggerConfig{
 /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.pjb.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
        /**
     * 创建该API的基本信息(这些基本信息会展现在文档页面中)
     * 访问地址:http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact=new Contact("作者名",
          "http://zjc.com","email地址");
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2")
                .description("Hello Swagger2")
                //.termsOfServiceUrl("http://www.jianshu.com/u/f192766abeab")
                //.contact("作者名")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

然后通过创建实体类和controller来简单测试下

@RestController
@RequestMapping("user")
public class UserController {
    @Autowired
    UserService userService;
    @GetMapping(value="/findAll")
    @ApiOperation(value = "查询所有用户",httpMethod ="GET", response = User.class,notes = "HelloWorld")
    public List<User> findAll(){
        return userService.findAll();
    }
}

注意:

记得在UserController中需要id输入的方法的注解少了个参数配置: paramType=“path”,不然所有的参数类型都会是body,获取不到请求参数。例如

@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Long”,paramType = “path”);


访问:http://localhost:8080/swagger-ui.html

就能看到前文所展示的RESTful API的页面。

202007182223547.jpg

我们还可以进行Try it out 进行测试,赶紧试试吧,满意请点赞收藏,么么哒

相关文章
|
5月前
|
前端开发 安全 Java
Spring Boot 便利店销售系统项目分包设计解析
本文深入解析了基于Spring Boot的便利店销售系统分包设计,通过清晰的分层架构(表现层、业务逻辑层、数据访问层等)和模块化设计,提升了代码的可维护性、复用性和扩展性。具体分包结构包括`controller`、`service`、`repository`、`entity`、`dto`、`config`和`util`等模块,职责分明,便于团队协作与功能迭代。该设计为复杂企业级应用开发提供了实践参考。
196 0
|
2月前
|
Java 关系型数据库 MySQL
springboot项目集成dolphinscheduler调度器 实现datax数据同步任务
springboot项目集成dolphinscheduler调度器 实现datax数据同步任务
274 2
|
2月前
|
分布式计算 Java 大数据
springboot项目集成dolphinscheduler调度器 可拖拽spark任务管理
springboot项目集成dolphinscheduler调度器 可拖拽spark任务管理
106 2
|
2月前
|
Java 测试技术 Spring
简单学Spring Boot | 博客项目的测试
本内容介绍了基于Spring Boot的博客项目测试实践,重点在于通过测试驱动开发(TDD)优化服务层代码,提升代码质量和功能可靠性。案例详细展示了如何为PostService类编写测试用例、运行测试并根据反馈优化功能代码,包括两次优化过程。通过TDD流程,确保每项功能经过严格验证,增强代码可维护性与系统稳定性。
111 0
|
2月前
|
存储 Java 数据库连接
简单学Spring Boot | 博客项目的三层架构重构
本案例通过采用三层架构(数据访问层、业务逻辑层、表现层)重构项目,解决了集中式开发导致的代码臃肿问题。各层职责清晰,结合依赖注入实现解耦,提升了系统的可维护性、可测试性和可扩展性,为后续接入真实数据库奠定基础。
190 0
|
3月前
|
网络协议 Java
在SpringBoot项目中使用Netty实现远程调用
本文介绍了使用Netty解决网络连接性能问题的方法,重点讲解了Netty的NIO特性及其在SpringBoot中的应用。Netty作为高效的NIO框架,支持非阻塞IO,能通过单线程管理多个客户端连接,简化TCP/UDP套接字服务器开发。文章详细展示了Netty在SpringBoot中实现远程调用的过程,包括服务端与客户端代码实现、依赖配置及测试验证。通过示例代码,如`NettyServer`、`NettyClientUtil`等,清晰说明了Netty的工作原理和实际应用,解决了半包等问题,并提供了完整的测试结果。
416 3
|
5月前
|
SQL 前端开发 Java
深入理解 Spring Boot 项目中的分页与排序功能
本文深入讲解了在Spring Boot项目中实现分页与排序功能的完整流程。通过实际案例,从Service层接口设计到Mapper层SQL动态生成,再到Controller层参数传递及前端页面交互,逐一剖析每个环节的核心逻辑与实现细节。重点包括分页计算、排序参数校验、动态SQL处理以及前后端联动,确保数据展示高效且安全。适合希望掌握分页排序实现原理的开发者参考学习。
277 4
|
前端开发 安全 Java
Swagger——【SpringBoot集成Swagger、配置Swagger、配置扫描接口、配置API分组】
Swagger——【SpringBoot集成Swagger、配置Swagger、配置扫描接口、配置API分组】
Swagger——【SpringBoot集成Swagger、配置Swagger、配置扫描接口、配置API分组】
|
Java Maven
【SpringBoot专题_02】springboot集成Swagger详细教程
【SpringBoot专题_02】springboot集成Swagger详细教程
105 0
|
Java
SpringBoot集成swagger后出现: Failed to start bean ‘documentationPluginsBootstrapper‘的解决方法
SpringBoot集成swagger后出现: Failed to start bean ‘documentationPluginsBootstrapper‘的解决方法
847 0