精华内容
下载资源
问答
  • Swagger2生成API接口文档
    2022-02-03 08:30:21

    1. Swagger2介绍

    前后端分离开发模式中,api文档是最好的沟通方式。
    Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

    2. 引入Swagger2依赖

    引入pom依赖,
    注意:父工程没有指明依赖版本的情况下,还需要指明swagger依赖的版本

    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <scope>provided </scope>
    </dependency>
    <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <scope>provided </scope>
    </dependency>
    

    3. 创建配置类

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
    
        @Bean
        public Docket webApiConfig(){
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                    .paths(Predicates.not(PathSelectors.regex("/error.*")))
                    .build();
    
        }
    
        private ApiInfo webApiInfo(){
    
            return new ApiInfoBuilder()
                    .title("网站-课程中心API文档")
                    .description("本文档描述了课程中心微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("Helen", "http://xbd.com", "88888888@qq.com"))
                    .build();
        }
    }
    

    4. 定义接口说明和参数说明

    定义在类上:@Api
    定义在方法上:@ApiOperation
    定义在参数上:@ApiParam

    @Api(description="讲师管理")
    @RestController
    @RequestMapping("/admin/edu/teacher")
    public class TeacherAdminController {
    
        @Autowired
        private TeacherService teacherService;
    
        @ApiOperation(value = "所有讲师列表")
        @GetMapping
        public List<Teacher> list(){
            return teacherService.list(null);
        }
    
        @ApiOperation(value = "根据ID删除讲师")
        @DeleteMapping("{id}")
        public boolean removeById(
                @ApiParam(name = "id", value = "讲师ID", required = true)
                @PathVariable String id){
            return teacherService.removeById(id);
        }
    }
    

    5.添加自定义设置

    给属性定义样例数据

    @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;
    

    接下来就可以访问 http://localhost:8080/swagger-ui.html 进行测试了

    更多相关内容
  • 配置Swagger2生成API接口文档 Swagger2介绍 前后端分离开发模式中,api文档是最好的沟通方式。 Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 及时性 (接口变更后,能够...

    配置Swagger2生成API接口文档

    Swagger2介绍

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

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

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

    配置Swagger2

    1、创建common模块

    在guli-parent下创建模块common

    配置:

    groupId:com.atguigu

    artifactId:common

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-QQ9wjEOl-1647752621053)(file:///C:/Users/admin/Documents/My Knowledge/temp/aada719b-e32a-40d5-909e-16c6bc992e89/128/index_files/9a40d77c-6b22-4f24-a288-c76d1082f98d.png)]

    2、在common中引入相关依赖

     <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
                <scope>provided </scope>
            </dependency>
            <!--mybatis-plus-->
            <dependency>
                <groupId>com.baomidou</groupId>
                <artifactId>mybatis-plus-boot-starter</artifactId>
                <scope>provided </scope>
            </dependency>
            <!--lombok用来简化实体类:需要安装lombok插件-->
            <dependency>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <scope>provided </scope>
            </dependency>
            <!--swagger-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <scope>provided </scope>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <scope>provided </scope>
            </dependency>
            <!-- redis -->
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-data-redis</artifactId>
            </dependency>
            <!-- spring2.X集成redis所需common-pool2
            <dependency>
                <groupId>org.apache.commons</groupId>
                <artifactId>commons-pool2</artifactId>
                <version>2.6.0</version>
            </dependency>-->
        </dependencies>
    

    3、在common下面创建子模块service-base

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-JDvnt8WW-1647752621055)(file:///C:/Users/admin/Documents/My Knowledge/temp/aada719b-e32a-40d5-909e-16c6bc992e89/128/index_files/73e4a0be-72b8-4ba2-9f15-76a0246c3ffa.png)]

    在模块service-base中,创建swagger的配置类

    创建包com.atguigu.servicebase.config,创建类SwaggerConfig

    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket webApiConfig(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("webApi")
                    .apiInfo(webApiInfo())
                    .select()
                    .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
                    .paths(Predicates.not(PathSelectors.regex("/error.*")))
                    .build();
        }
        
        private ApiInfo webApiInfo(){
            return new ApiInfoBuilder()
                    .title("网站-课程中心API文档")
                    .description("本文档描述了课程中心微服务接口定义")
                    .version("1.0")
                    .contact(new Contact("Helen", "http://atguigu.com", "55317332@qq.com"))
                    .build();
        }
    }
    

    4、在模块service模块中引入service-base

    <dependency>
        <groupId>com.atguigu</groupId>
        <artifactId>service-base</artifactId>
        <version>0.0.1-SNAPSHOT</version>
    </dependency>
    

    5、在service-edu启动类上添加注解,进行测试

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-gu72E4vV-1647752621056)(file:///C:/Users/admin/Documents/My Knowledge/temp/aada719b-e32a-40d5-909e-16c6bc992e89/128/index_files/ef45a37b-8f5b-480e-9d85-e25bf5bdd3ce.png)]

    API模型

    可以添加一些自定义设置,例如:

    定义样例数据

    @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;
    

    [外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-Ykzb9WFC-1647752621057)(file:///C:/Users/admin/Documents/My Knowledge/temp/aada719b-e32a-40d5-909e-16c6bc992e89/128/index_files/9c17851c-8e7e-4161-968c-18b36faf148a.png)]

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

    定义在类上:@Api

    定义在方法上:@ApiOperation

    定义在参数上:@ApiParam

    @Api(description="讲师管理")
    @RestController
    @RequestMapping("/admin/edu/teacher")
    public class TeacherAdminController {
        @Autowired
        private TeacherService teacherService;
        @ApiOperation(value = "所有讲师列表")
        @GetMapping
        public List<Teacher> list(){
            return teacherService.list(null);
        }
        @ApiOperation(value = "根据ID删除讲师")
        @DeleteMapping("{id}")
        public boolean removeById(
                @ApiParam(name = "id", value = "讲师ID", required = true)
                @PathVariable String id){
            return teacherService.removeById(id);
        }
    }
    
    展开全文
  • swagger2的配置 package com.itcodai.course01.Swagger2Test; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox....

    swagger2的配置

    package com.itcodai.course01.Swagger2Test;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig {
        @Bean
        public Docket creatRestApi(){
            return new Docket(DocumentationType.SWAGGER_2)
                    //指定构建api文档的详细信息的方法:apiInfo()
                    .apiInfo(apiInfo())
                    .select()
                    //指定要生成api接口的包路径,这里把controller作为包路径,生成controller中的所有接口
            .apis(RequestHandlerSelectors.basePackage("com.itcodai.course01.Swagger2Test"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //设置页面标题
                    .title("Spring Boot集成Swagger2接口总览")
                    //设置接口描述
                    .description("跟学spring boot")
                    //设置联系方式
                    .contact("sss," + "xxxxxxxxxx")
                    //设置版本
                    .version("1.0")
                    //构建
                    .build();
        }
    }
    

    实体类注解

    package com.itcodai.course01.Swagger2Test;
    
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    @ApiModel(value = "用户实体类")
    public class User {
    
        @ApiModelProperty(value = "用户唯一标识")
        private Long id;
    
        @ApiModelProperty(value = "用户姓名")
        private String username;
    
        @ApiModelProperty(value = "用户密码")
        private String userPassword;
        
        //省略构造方法,set和get方法
    
    • 解释@ApiModel* 和 @ApiModelProterty 注解

    @ApiModel 注解用于实体类,表示对类进行说明,用于参数用实体类接收。
    @ApiModelProperty 注解用于类中属性,表示对 model 属性的说明或者数据操作更改。

    Controller类中的注解

    package com.itcodai.course01.Swagger2Test;
    
    
    import com.itcodai.course01.jsonTest.JsonResult;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RestController;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @EnableSwagger2
    @RestController
    @RequestMapping("/swagger")
    @Api(value = "Swagger2 在线接口文档")
    public class TestController2 {
        @GetMapping("/get/{id}")
        @ApiOperation(value = "根据用户唯一标识获取用户信息")
        public JsonResult<User> getUserInfo(@PathVariable @ApiParam(value = "用户唯一标识") Long id) {
            //模拟数据库中根据id获取User信息
            User user = new User(id, "xxx", "123432423");
            return new JsonResult(user);
        }
    }
    
    • @Api@ApiOperation@ApiParam 注解。

    @Api 注解用于类上,表示标识这个类是 swagger 的资源。
    @ApiOperation 注解用于方法,表示一个 http 请求的操作。
    @ApiParam 注解用于参数上,用来标明参数信息。

    实践中出现的错误

    出现的错误:http://localhost:8001/swagger-ui.htm没有出现新增的接口 ,且程序没有报错
    原因:最开头swagger2配置中的23行代码
    .apis(RequestHandlerSelectors.basePackage(“com.itcodai.course01.Swagger2Test”))
    引号包含的部分为java中包路径,即将该包中文件形成api。而路径错误导致swagger2 没有找到接口。
    解决方法:每个类第一行就是该类的包路径,直接粘贴复制可以防止错误

    展开全文
  • 使用maven+springboot+swagger3+idea生成swagger API文档的演示示例。
  • 一、问题背景 随着技术的发展,现在的开发模式已经更多的转向了前后端分离的模式,在前后端开发的过程中,联系的方式也变成...Swagger可以从不同的代码中,根据注释生成API信息,swagger拥有强大的社区,并且对于各种语
  • spring-boot作为当前最为流行的Java web...假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝,那么尝试一下Swagger2 方式,一定会让你有不一样的开发体验: 功能丰富 :支持多种注解,自动生成接口文档界面

    spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。在实际开发过程中,这些接口还要提供给开发测试进行相关的白盒测试,那么势必存在如何在多人协作中共享和及时更新API开发接口文档的问题。
    假如你已经对传统的wiki文档共享方式所带来的弊端深恶痛绝,那么尝试一下Swagger2 方式,一定会让你有不一样的开发体验:

    • 功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
    • 及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
    • 整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。

    1、添加pom依赖

    需要添加的依赖为swagger2核心包和swagger-ui界面包,笔者写文章时的最新版本为2.7.0,实际引用可以去maven官网查询最新可使用版本。

    代码块

    <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、将swagger-ui中的界面配置至spring-boot环境

    spring-boot有自己的一套web端拦截机制,若需要看到swagger发布的api文档界面,需要做一些特殊的配置,将springfox-swagger-ui包中的ui界面暴露给spring-boot资源环境。

    代码块

    @Configuration
    public class WebMvcConfig extends WebMvcConfigurerAdapter {
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
            registry.addResourceHandler("swagger-ui.html")
                    .addResourceLocations("classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**")
                    .addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    
    }
    

    3、配置API文档页基本信息

    spring-boot 和 swagger 整合时,可以通过注解注入相关配置。通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹,另外可以指定API文档页的标题和描述信息等内容。

    代码块

    @Configuration
    @EnableSwagger2
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.xx.web.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("xx项目 RESTful APIs")
                    .description("xx项目后台api接口文档")
                    .version("1.0")
                    .build();
        }
    
    }
    

    4、API文档编写示例

    我们一般在Controller层,将详尽的API接口输入输出在代码中通过注解进行相关描述,下面给出一个接口描写示例,具体的写法可以参考其api文档的具体说明:

    代码块

    @Api(value = "PageController", description = "用户登录登出接口")
    @Controller
    @RequestMapping("/")
    public class PageController {
    
        @ApiOperation(value="用户登录", notes="用户登录接口")
        @ApiImplicitParams({
              @ApiImplicitParam(name = "username", value = "用户名", required = true ,dataType = "string"),
              @ApiImplicitParam(name = "passwd", value = "密码", required = true ,dataType = "string")
        })
        @RequestMapping(value = "/login",method = {RequestMethod.POST,RequestMethod.GET})
        @ResponseBody
        public ModelMap login(Users data, HttpServletRequest request){
           xxx...
        }
    
    }
    

    5、在线查看及测试API文档

    完成API文档的编写工作之后,正常启动spring-boot,假如后台端口为8080,那么访问http://127.0.0.1:8080/swagger-ui.html,可以访问到如下界面:

    通过该界面,不仅可以看到自动生成的所有API文档信息,还可以对任意接口进行在线测试,非常方便:

     

     

    展开全文
  • 文章目录1. Swagger2介绍2. 配置Swagger22.1 创建common模块2.2 在common中引入相关依赖2.3 在common下面创建子模块service-base2.4 在模块service-base中,创建...前后端分离开发模式中,api文档是最好的沟通方式。
  • 文章目录前言一、Swagger介绍二、配置Swagger1....今天就来说一说如何整合Swagger生成一套漂亮、美观、实用的接口文档。 源码传送门:https://gitee.com/huoqstudy/xiliu-admin.git 一、Swagger介绍
  • 在开发过程中,我们请求的接口的时候,往往都是后台我们一个接口文档,便于我们查阅,今天我们就用node生成一个自己的接口文档 ,知道接口文档怎么来的。 这里不在讲解node怎么安装,接口怎么写,直接写接口文档生成...
  • 前后端分离开发模式中,api文档是最好的沟通方式。 Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 及时性 (接口变更后,能够及时准确地通知相关前后端开发人员) 规范性 ...
  • 步骤一:导入依赖,注意SWAGGER和UI最好保持版本一致,否则可能会遇到不同的坑 <!-- swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-...
  • asp.net webapi集成swagger自动生成接口文档(亲测可用)swagger生成html离线接口文档swagger生成html离线接口文档
  • Spring Boot 使用 Swagger3 生成 API 接口文档

    千次阅读 多人点赞 2022-01-08 21:31:04
    主要介绍如何使用 Spring Boot 集成 Swagger3,构建我们自己的 API 接口文档,并对比了 Swagger2Swagger3 的区别,让我们从 Swagger2Swagger3 过渡更加顺滑。
  • 加速您在Express上熟练的文档体验。 声波加速Express上的草率文档体验。 这是做什么的? 这将与Express res和req API挂钩,并为您自动记录每个响应,因此您不必这样做。 想象一下编写100个API并将其完整记录下来,这...
  • 【Go开源宝藏】:Go-Swagger 自动生成api接口文档
  • 利用swagger生成api接口文档

    千次阅读 2019-06-07 23:55:03
    1. swagger出现的背景? 现在的网站架构,前后端分离已经成为一种趋势,前后端的技术在各自的道路上越走远越,后端的框架有常见的spring全家桶,前段也有...但在实际开发中往往api文档不能及时更新,带来一些问题...
  • 主要介绍了SpringBoot结合Swagger2自动生成api文档的方法,小编觉得挺不错的,现在分享给大家,也给大家做个参考。一起跟随小编过来看看吧
  • RuoYi框架swagger自动生成API接口文档

    千次阅读 2021-06-14 11:17:49
    1、若依系统会自带有swagger生成接口文档,登录若依系统后可以在 这里查看系统的接口demo。 如果想更改这个接口文档的样式可以参考地址: https://blog.csdn.net/qq_22734863/article/details/113341869 2、我修改...
  • 什么是SwaggerSwagger是一款Restful接口的文档在线自动生成和功能测试功能软件。 Swagger是一个规范和完整的框架,用于生成、描述...--Swagger-UI API文档生产工具--> <dependency> <groupId>.
  • Web API安装swagger控件,自动生成api接口文档,内含流程文档和测试源码
  • SpringBoot集成Swagger2生成API接口文档

    千次阅读 2020-06-13 09:43:55
    SpringBoot2.3.0集成Swagger2引入Swagger2相应的依赖入门示例SpringBoot2集成Swagger2后启动报错结语 背景:最近在工作中发现,已经多次发现后台开发人员提供的接口协议和实际的业务代码不统一。这些现象往往都是...
  • 文章目录1、引入swagger框架2、引入jackson框架3、配置swagger4、添加swagger资源文件的映射5、Controller代码6、访问学生管理的接口文档7、使用swagger调用学生管理接口 1、引入swagger框架 <!-- ...
  • SpringCloud整合Swagger生成API接口文档1.Swagger2介绍2.配置Swagger23.创建swagger的配置类然后创建一个java类,并且在这个类加入@Configuration和@EnableSwagger2注解4.使用Swagger2功能5.在需要Swagger2模块的...
  • Swagger本质上是一种用于描述使用JSON表示的RESTful API接口描述语言。Swagger与一组开源软件工具一起使用,以设计、构建、记录和使用RESTful Web服务。Swagger包括自动文档,代码生成和测试用例生成。 在前后端...
  • 一份关于使用Swagger自动生成API说明文档的开发文档
  • 光纤中间件,以使用Swagger 2.0自动生成RESTful API文档。 用法 开始使用它 将注释添加到您的API源代码中,。 使用以下方法下载 for Go: $ go get -u github.com/swaggo/swag/cmd/swag 在包含main.go文件的Go项目...
  • Swagger可以帮我们实现生成api接口文档 适用于 Teams | 的 API 文档和设计工具斯瓦格 (swagger.io)
  • swagger2Word 提供了多种方式生成 word 文档,可以通过 swagger json 的资源地址,例如: ;可以通过上传 json 文件;甚至可以直接输入 json 字符串。 生成的 WORD 示例: --------------版本迭代历程,感谢各位小...

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 20,568
精华内容 8,227
关键字:

swagger2生成api接口文档