Jadual Kandungan
引入 Swagger2 依赖
创建配置文件
Rumah Java javaTutorial SpringBoot集成Swagger2生成接口文档,妈妈再也不用担心我写API文档了

SpringBoot集成Swagger2生成接口文档,妈妈再也不用担心我写API文档了

May 26, 2020 pm 06:36 PM
1

在现在的开发过程中,基本已经全部采用 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>
Salin selepas log masuk

创建配置文件

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();
    }
}
Salin selepas log masuk

application.yml 配置文件

swagger2:
  enable: false #true 启用
Salin selepas log masuk

@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){
  ...
 }
}
Salin selepas log masuk

最后在运行 SpringBoot 项目之后,通过 服务器地址/swagger-ui.html 访问即可。

需要注意的是,如已添加路径拦截器,需通过

.excludePathPatterns("/swagger-resources/**", "/webjars/**", "/v2/**", "/swagger-ui.html/**")
Salin selepas log masuk

对 swagger 路径放行。

Atas ialah kandungan terperinci SpringBoot集成Swagger2生成接口文档,妈妈再也不用担心我写API文档了. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!

Kenyataan Laman Web ini
Kandungan artikel ini disumbangkan secara sukarela oleh netizen, dan hak cipta adalah milik pengarang asal. Laman web ini tidak memikul tanggungjawab undang-undang yang sepadan. Jika anda menemui sebarang kandungan yang disyaki plagiarisme atau pelanggaran, sila hubungi admin@php.cn

Alat AI Hot

Undresser.AI Undress

Undresser.AI Undress

Apl berkuasa AI untuk mencipta foto bogel yang realistik

AI Clothes Remover

AI Clothes Remover

Alat AI dalam talian untuk mengeluarkan pakaian daripada foto.

Undress AI Tool

Undress AI Tool

Gambar buka pakaian secara percuma

Clothoff.io

Clothoff.io

Penyingkiran pakaian AI

AI Hentai Generator

AI Hentai Generator

Menjana ai hentai secara percuma.

Artikel Panas

R.E.P.O. Kristal tenaga dijelaskan dan apa yang mereka lakukan (kristal kuning)
3 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. Tetapan grafik terbaik
3 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. Cara Memperbaiki Audio Jika anda tidak dapat mendengar sesiapa
3 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌
WWE 2K25: Cara Membuka Segala -galanya Di Myrise
4 minggu yang lalu By 尊渡假赌尊渡假赌尊渡假赌

Alat panas

Notepad++7.3.1

Notepad++7.3.1

Editor kod yang mudah digunakan dan percuma

SublimeText3 versi Cina

SublimeText3 versi Cina

Versi Cina, sangat mudah digunakan

Hantar Studio 13.0.1

Hantar Studio 13.0.1

Persekitaran pembangunan bersepadu PHP yang berkuasa

Dreamweaver CS6

Dreamweaver CS6

Alat pembangunan web visual

SublimeText3 versi Mac

SublimeText3 versi Mac

Perisian penyuntingan kod peringkat Tuhan (SublimeText3)

Bagaimanakah mekanisme kelas muatan Java berfungsi, termasuk kelas yang berbeza dan model delegasi mereka? Bagaimanakah mekanisme kelas muatan Java berfungsi, termasuk kelas yang berbeza dan model delegasi mereka? Mar 17, 2025 pm 05:35 PM

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

Bagaimanakah saya melaksanakan caching pelbagai peringkat dalam aplikasi java menggunakan perpustakaan seperti kafein atau cache jambu? Bagaimanakah saya melaksanakan caching pelbagai peringkat dalam aplikasi java menggunakan perpustakaan seperti kafein atau cache jambu? Mar 17, 2025 pm 05:44 PM

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

Bagaimanakah saya boleh menggunakan JPA (Java Constence API) untuk pemetaan objek-objek dengan ciri-ciri canggih seperti caching dan malas malas? Bagaimanakah saya boleh menggunakan JPA (Java Constence API) untuk pemetaan objek-objek dengan ciri-ciri canggih seperti caching dan malas malas? Mar 17, 2025 pm 05:43 PM

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]

Bagaimanakah saya menggunakan Maven atau Gradle untuk Pengurusan Projek Java Lanjutan, Membina Automasi, dan Resolusi Ketergantungan? Bagaimanakah saya menggunakan Maven atau Gradle untuk Pengurusan Projek Java Lanjutan, Membina Automasi, dan Resolusi Ketergantungan? Mar 17, 2025 pm 05:46 PM

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

Bagaimanakah saya membuat dan menggunakan perpustakaan Java Custom (fail JAR) dengan pengurusan versi dan pergantungan yang betul? Bagaimanakah saya membuat dan menggunakan perpustakaan Java Custom (fail JAR) dengan pengurusan versi dan pergantungan yang betul? Mar 17, 2025 pm 05:45 PM

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

See all articles