SpringBoot集成Swagger2生成接口文档,妈妈再也不用担心我写API文档了
在现在的开发过程中,基本已经全部采用 API 接口的方式进行系统的开发了,于是乎,在此过程中,一个好的 API 文档便成为了后台与前台进行沟通与开发的关键桥梁。
传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,说实话,这样的工作量并不小,而且十分琐碎,且随着项目的更新会出现以下问题。
文档难以维护。
接口内容更加复杂,编写效率更低。
Swagger 便是为了解决这一问题,它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:
通过Swagger,我们可以在开发接口的过程中通过使用注解自动生成/更新 API 接口文档,且在文档页面支持接口的调试。
接下来就简单说一下,如何在 SpringBoot 中集成 Swagger2(2 代表其版本)
引入 Swagger2 依赖
pom.xml 文件
<dependencies> <!--Swagger2 在此,个人推荐使用2.8.0版本,较为稳定--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> </dependencies>
创建配置文件
Swagger2Config.java java 配置文件
@Configuration // 指定扫描的api包路径 @ComponentScan(basePackages = {"cn.beatree.xxx.controller"}) //注解开启 swagger2 功能 @EnableSwagger2 public class Swagger2Config { @Value("${swagger2.enable}") boolean enable; // 配置文件中通过值注入控制生产环境与开发环境下的启用状态 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .enable(enable) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("ANONVOTE | Swagger API文档")//标题 .description("description: ANONVOTE | Swagger API文档")//描述 .contact("BEATREE")//作者信息 .version("1.0.0")//版本号 .build(); } }
application.yml 配置文件
swagger2: enable: false #true 启用
@Configuration 注解,指定为配置类,会在 SpringBoot 启动时进行加载。
@EnableSwagger2 注解来启用 Swagger2。
成员方法 createRestApi 函数创建 Docket 的 Bean 之后,apiInfo() 用来创建该 Api 的基本信息(这些基本信息会展现在文档页面中)。select() 函数返回一个 ApiSelectorBuilder 实例用来控制哪些接口暴露给 Swagger 来展现,本例采用指定扫描的包路径来定义,Swagger 会扫描该包下所有 Controller 定义的 API,并产生文档内容(除了被 @ApiIgnore 指定的请求)。
常用 Swagger 注解
@Api:修饰整个类,描述 Controller 的作用
@ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数描述@ApiModel:用对象来接收参数
@ApiProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP 响应其中 1 个描述
@ApiResponses:HTTP 响应整体描述
@ApiIgnore:使用该注解忽略这个 API
@ApiError :发生错误返回的信息
@ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
@ApiImplicitParams:描述由多个
@ApiImplicitParam 注解的参数组成的请求参数列表
举个栗子
@RestController @Transactional // 事务注解,实现回滚 @RequestMapping("/api/tlink") @Api(value = "/api/tlink", tags = "参与者相关接口") public class TlinkController{ @GetMapping("/checkCode/{code}") @ApiOperation(value = "投票认证码核验接口", notes = "该接口用于核验认证码合法性,对于投票主题内容的获取需后续调用Topic相关接口。返回值data中带有参数 topic & options") public JSONObject checkCode(@PathVariable("code") String code){ ... } }
最后在运行 SpringBoot 项目之后,通过 服务器地址/swagger-ui.html 访问即可。
需要注意的是,如已添加路径拦截器,需通过
.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")
对 swagger 路径放行。
Atas ialah kandungan terperinci SpringBoot集成Swagger2生成接口文档,妈妈再也不用担心我写API文档了. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!

Alat AI Hot

Undresser.AI Undress
Apl berkuasa AI untuk mencipta foto bogel yang realistik

AI Clothes Remover
Alat AI dalam talian untuk mengeluarkan pakaian daripada foto.

Undress AI Tool
Gambar buka pakaian secara percuma

Clothoff.io
Penyingkiran pakaian AI

AI Hentai Generator
Menjana ai hentai secara percuma.

Artikel Panas

Alat panas

Notepad++7.3.1
Editor kod yang mudah digunakan dan percuma

SublimeText3 versi Cina
Versi Cina, sangat mudah digunakan

Hantar Studio 13.0.1
Persekitaran pembangunan bersepadu PHP yang berkuasa

Dreamweaver CS6
Alat pembangunan web visual

SublimeText3 versi Mac
Perisian penyuntingan kod peringkat Tuhan (SublimeText3)

Topik panas



Kelas kelas Java melibatkan pemuatan, menghubungkan, dan memulakan kelas menggunakan sistem hierarki dengan bootstrap, lanjutan, dan pemuat kelas aplikasi. Model delegasi induk memastikan kelas teras dimuatkan dahulu, yang mempengaruhi LOA kelas tersuai

Artikel ini membincangkan pelaksanaan caching pelbagai peringkat di Java menggunakan kafein dan cache jambu untuk meningkatkan prestasi aplikasi. Ia meliputi persediaan, integrasi, dan faedah prestasi, bersama -sama dengan Pengurusan Dasar Konfigurasi dan Pengusiran PRA Terbaik

Artikel ini membincangkan menggunakan JPA untuk pemetaan objek-relasi dengan ciri-ciri canggih seperti caching dan pemuatan malas. Ia meliputi persediaan, pemetaan entiti, dan amalan terbaik untuk mengoptimumkan prestasi sambil menonjolkan potensi perangkap. [159 aksara]

Artikel ini membincangkan menggunakan Maven dan Gradle untuk Pengurusan Projek Java, membina automasi, dan resolusi pergantungan, membandingkan pendekatan dan strategi pengoptimuman mereka.

Artikel ini membincangkan membuat dan menggunakan perpustakaan Java tersuai (fail balang) dengan pengurusan versi dan pergantungan yang betul, menggunakan alat seperti Maven dan Gradle.
