如何快速上手在项目中使用Swagger进行API文档编写？

本文共计698个文字，预计阅读时间需要3分钟。

Swagger使用：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful Web服务的接口文档。作用：当前项目基本都采用前后端分离，后端负责后端。

Swagger使用

swagger定义与作用：

定义：Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

作用：目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。说白了swagger就是会自动帮我们写接口说明文档的工具。

springboot集成swagger

swagger项目必须要写controller跳转的才能正常进入页面！！！

1.新建springboot的web项目

2.导入swagger依赖包

<!-- mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.0.0</version> </dependency> <!-- mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>3.0.0</version> </dependency>

3.在spring中写配置config

package com.swagger.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; /** * @author panglili * @create 2022-07-11-17:14 */ @Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { private static ApiInfo apiInfo(){ //作者信息 Contact contact = new Contact( "tata", "www.cnblogs.com/lumanmanqixiuyuanxi/", "2558008051@qq.com"); return new ApiInfo( "tata swagger api", "Api Documentation", "1.0", "www.cnblogs.com/lumanmanqixiuyuanxi/", contact, "Apache 2.0", "www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } @Bean public Docket docket(){ //enable()是否开启swagger，false则关闭不能在浏览器访问 //paths()访问经过controller中指定请求路径下的请求 return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) // .enable(false) .select() .apis(RequestHandlerSelectors.basePackage("com.swagger.controller")) // .paths(PathSelectors.ant("/hello/*")) .build(); } }

4.访问swagger

localhost:8080/swagger-ui.html#

5.分组实现团队开发功能

@Bean public Docket docket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("A"); } @Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("B"); } @Bean public Docket docket1(){ return new Docket(DocumentationType.SWAGGER_2).groupName("C"); }

只需要在config中定义不同名的docket，分组功能就实现了！！！

6.swagger扫描实体类在文档中

在实体类中swagger注解可以在生成的文档上面添加上注解。只需要在controller中配置相应的实体类就会被swagger自动识别到。

package com.swagger.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; /** * @author panglili * @create 2022-07-11-21:27 */ @ApiModel("用户实体类") public class User { @ApiModelProperty("用户名") public String username; @ApiModelProperty("密码") public String password; }

//返回了实体类才会被swagger自动扫描到，然后再swagger文档中的models中展示。 @RequestMapping("/user") public User user(){ return new User(); }