配置 swagger

作者：卢卡多多

2022 年 6 月 17 日
本文字数：1758 字
阅读完需：约 6 分钟

一、Swagger2 介绍

https://swagger.io/

前后端分离开发模式中，api 文档是最好的沟通方式。

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

及时性 (接口变更后，能够及时准确地通知相关前后端开发人员)
规范性 (并且保证接口的规范性，如接口的地址，请求方式，参数及响应格式和错误信息)
一致性 (接口信息一致，不会出现因开发人员拿到的文档版本不一致，而出现分歧)
可测性 (直接在接口文档上进行测试，以方便理解业务)

二、配置 Swagger2

1、相关依赖

<!--swagger-->

复制代码

<dependency>

复制代码

    <groupId>io.springfox</groupId>

复制代码

    <artifactId>springfox-swagger2</artifactId>

复制代码

    <version>2.7.0</version>

复制代码

</dependency>

复制代码

<dependency>

复制代码

    <groupId>io.springfox</groupId>

复制代码

    <artifactId>springfox-swagger-ui</artifactId>

复制代码

    <version>2.7.0</version>

复制代码

</dependency>

复制代码

2、创建 Swagger2 配置文件

package com.guli.edu.config;

复制代码

@Configuration

复制代码

@EnableSwagger2

复制代码

public class Swagger2Config {

复制代码

    @Bean

复制代码

    public Docket webApiConfig(){

复制代码

        return new Docket(DocumentationType.SWAGGER_2)

复制代码

                .groupName("webApi")

复制代码

                .apiInfo(webApiInfo())

复制代码

                .select()

复制代码

                //过滤掉admin路径下的所有页面

复制代码

                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))

复制代码

                //过滤掉所有error或error.*页面

复制代码

                .paths(Predicates.not(PathSelectors.regex("/error.*")))

复制代码

                .build();

复制代码

    @Bean

复制代码

    public Docket adminApiConfig(){

复制代码

        return new Docket(DocumentationType.SWAGGER_2)

复制代码

                .groupName("adminApi")

复制代码

                .apiInfo(adminApiInfo())

复制代码

                .select()

复制代码

                //只显示admin路径下的页面

复制代码

                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))

复制代码

                .build();

复制代码

    private ApiInfo webApiInfo(){

复制代码

        return new ApiInfoBuilder()

复制代码

                .title("网站-课程中心API文档")

复制代码

                .description("本文档描述了课程中心微服务接口定义")

复制代码

                .version("1.0")

复制代码

                .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))

复制代码

                .build();

复制代码

    private ApiInfo adminApiInfo(){

复制代码

        return new ApiInfoBuilder()

复制代码

                .title("后台管理系统-课程中心API文档")

复制代码

                .description("本文档描述了后台管理系统课程中心微服务接口定义")

复制代码

                .version("1.0")

复制代码

                .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))

复制代码

                .build();

复制代码

3、重启服务器查看接口

http://localhost:8110/swagger-ui.html

4、API 模型

entity 的实体类中可以添加一些自定义设置，例如：

定义样例数据\

@ApiModelProperty(value = "创建时间", example = "2019-01-01 8:00:00")

复制代码

@TableField(fill = FieldFill.INSERT)

复制代码

private Date gmtCreate;

复制代码

@ApiModelProperty(value = "更新时间", example = "2019-01-01 8:00:00")

复制代码

@TableField(fill = FieldFill.INSERT_UPDATE)

复制代码

private Date gmtModified;

复制代码

5、定义接口说明和参数说明

定义在类上：@Api

定义在方法上：@ApiOperation

定义在参数上：@ApiParam

@Api(description="讲师管理")

复制代码

@RestController

复制代码

@RequestMapping("/admin/edu/teacher")

复制代码

public class TeacherAdminController {

复制代码

    @Autowired

复制代码

    private TeacherService teacherService;

复制代码

    @ApiOperation(value = "所有讲师列表", notes = "返回所有讲师列表")

复制代码

    @GetMapping

复制代码

    public List<Teacher> list(){

复制代码

        return teacherService.list(null);

复制代码

    @ApiOperation(value = "根据ID删除讲师", notes = "根据ID删除讲师")

复制代码

    @DeleteMapping("{id}")

复制代码

    public boolean removeById(

复制代码

            @ApiParam(name = "id", value = "讲师ID", required = true)

复制代码

            @PathVariable String id){

复制代码

        return teacherService.removeById(id);

复制代码

发布于: 刚刚阅读数: 3

原文链接:【http://xie.infoq.cn/article/7595f54fc0f1e0e664752e3f7】。文章转载请联系作者。

卢卡多多

关注

努力寻找生活答案的旅途者 2020.04.12 加入

公众号：卢卡多多，欢迎一起交流学习 2021年度优质创作者

发布

暂无评论

创作场景

配置 swagger

一、Swagger2 介绍

二、配置 Swagger2

1、相关依赖

2、创建 Swagger2 配置文件

3、重启服务器查看接口

4、API 模型

5、定义接口说明和参数说明

卢卡多多

评论