精华内容
下载资源
问答
  • Spring-Boot + Swagger2 自动生成API接口文档
    2020-05-12 19:37:48

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

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

    Spring-Boot Swagger2 自动生成API接口文档

    1、添加pom依赖

    
            <!--swagger2依赖-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.7.0</version>
            </dependency>
            <!--swagger2-ui依赖-->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.7.0</version>
            </dependency>

    2. 创建Swagger2配置文件

    package com.config;
    
    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 createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.controller"))
                    .paths(PathSelectors.any())
                    .build()
                    .apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2")
                    .description("首次尝试自动生成api文档为后期的前后端分离开发做准备")
                    .termsOfServiceUrl("https://www.jianshu.com/u/2f60beddf923")
                    .contact("WEN")
                    .version("1.0")
                    .build();
        }
    }
    

    3.实体类model

    package com.model;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    import lombok.Data;
    
    @ApiModel("用户实体")
    @Data
    public class User {
        /**
         * 用户Id
         */
        @ApiModelProperty("用户id")
        private int id;
    
        /**
         * 用户名
         */
        @ApiModelProperty(value = "用户姓名", example = "zhangdan", required = true)
        private String name;
    
        /**
         * 用户地址
         */
        @ApiModelProperty(value = "用户地址", example = "北京市海淀区", required = true)
        private String address;
    
        /**
         * 用户手机号
         */
        @ApiModelProperty(value = "用户手机号", example = "15689652367", required = true)
        private String phone;
    
        /**
         * 用户年龄
         */
         @ApiModelProperty(value = "用户年龄", example = "24", required = true)
         private Integer age;
    }
    

    4.接口开发

    package com.controller;
    
    import com.model.User;
    import io.swagger.annotations.*;
    import org.springframework.web.bind.annotation.*;
    
    @RestController
    @RequestMapping("/user")
    @Api(tags = "用户相关接口", description = "提供用户相关的Rest API")
    public class UserController {
    
        @PostMapping("/add")
        @ApiOperation(value = "新增用户接口", notes = "手机号、密码都是必输项,年龄随边填,但必须是数字")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "name", value = "用户名称", required = true, paramType = "query"),
                @ApiImplicitParam(name = "address", value = "用户地址", required = true, paramType = "query"),
                @ApiImplicitParam(name = "phone", value = "用户手机号", required = true, paramType = "query"),
                @ApiImplicitParam(name = "age", value = "用户年龄", required = true, paramType = "query", dataType = "Integer")
        })
        public String addUser(@RequestBody User user) {
            return user.toString();
        }
    
        @ApiOperation("通过id查找用户接口")
        @GetMapping("/find/{id}")
        public User findById(@PathVariable("id") int id) {
            return new User();
        }
    
        @ApiOperation("更新用户信息接口")
        @PutMapping("/update")
        @ApiResponses({
                @ApiResponse(code = 400, message = "请求参数没填好"),
                @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对"),
                @ApiResponse(code = 405, message = "未知错误")
        })
        public boolean update(@RequestBody User user) {
            return true;
        }
    }
    

    swagger界面显示

      

    5. Swagger 2常用注解说明
    Swagger 2通过注解表明该API接口会生成文档,包括接口名称、请求方法、请求参数、返回信息的等等。

    Swagger 2.0使用的注解及其说明:@Api:用在类上,说明该类的作用。
    @ApiOperation:注解来给API增加方法说明。
    @ApiImplicitParams : 用在方法上包含一组参数说明。
    @ApiImplicitParam:用来注解来给方法入参增加说明。
    @ApiResponses:用于表示一组响应
    @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
    @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
    @ApiIgnore:使用该注解忽略这个API
    @ApiError :发生错误返回的信息
    作用范围    API    使用位置
    对象属性    @ApiModelProperty    用在出入参数对象的字段上
    协议集描述    @Api    用于controller类上
    协议描述    @ApiOperation    用在controller的方法上
    Response集    @ApiResponses    用在controller的方法上
    Response    @ApiResponse    用在 @ApiResponses里边
    非对象参数集    @ApiImplicitParams    用在controller的方法上
    非对象参数描述    @ApiImplicitParam    用在@ApiImplicitParams的方法里边
    描述返回对象的意义    @ApiModel    用在返回对象类上
     

     

     

     

    更多相关内容
  • 招摇文件生成器 根据jsdoc注释生成swagger文件。
  • 优化mybatis自动生成代码,实体类自动生成注释swagger的注解,可以自定义自己的注释格式,提高重复的代码编写
  • 根据最佳实践和简单的假设自动生成laravel项目的swagger文档
  • 在开发过程中,我们请求的接口的时候,往往都是后台我们一个接口文档,便于我们查阅,今天我们就用node生成一个自己的接口文档 ,知道接口文档怎么来的。 这里不在讲解node怎么安装,接口怎么写,直接写接口文档生成...
  • 生成swagger文档 编写代码注释 代码注释的字段参考:https://swaggo.github.io/swaggo.io/declarative_comments_format/ 代码注释分为两种: General API Info API Operation General API info 的注释需要放在...

    该功能参考github开源项目gin-swagger,github地址如下:https://github.com/swaggo/gin-swagger

    生成swagger文档

    编写代码注释

    代码注释的字段参考:https://swaggo.github.io/swaggo.io/declarative_comments_format/

    代码注释分为两种:

    General API info 的注释需要放在main函数的前面编写,主要是对API功能的一些基本介绍等等。

    // @title 质检中心API接口

    // @version 1.0

    // @description 质检中心API接口——质检任务列表相关接口

    // @contact.name xxx

    // @contact.email xxx@lenovo.com

    // @BasePath /hoicee/cqi/api

    func main() {

    ...

    }

    而API Operation则可以写在每个api处理方法前,用于写明API的功能,接收的参数类型,参数列表等等

    // QueryTaskList godoc

    // @Summary 请求质检任务列表

    // @Description 获取质检任务列表

    // @Accept json

    // @Produce json

    // @Param appKey query string true "appKey"

    // @Param timestamp query int true "时间戳"

    // @Param sign query string true "签名"

    // @Param jsonStr query object true "请求参数"

    // @Success 200 {object} api.TaskListResponseData

    // @Failure 400 {object} api.ResponseBase

    // @Failure 404 {object} api.ResponseBase

    // @Failure 500 {object} api.ResponseBase

    // @Router /v1/items/list [get]

    func ProcessQueryTaskList(c *gin.Context) {

    ...

    }

    重点说明一下Success及Failure的最后一个参数, 如上面例子中的api.TaskListResponseData,其实是对应到你项目中api包下的一个结构体,名字叫做TaskListResponseData,swag会自动解析这个结构体中的json tag,来生成对应的响应结构。

    生成swagger文档

    1.安装swag

    go get -u github.com/swaggo/swag/cmd/swag

    2.下载gin-swagger

    go get -u github.com/swaggo/gin-swagger

    go get -u github.com/swaggo/files

    3.在main.go的根目录下,执行

    swag init

    此时swag会在main.go的根目录中生成docs目录

     该目录中就包含了根据代码注释生成的swagger格式的文档。文件类型包括json、yam两种

    引入gin-swagger

    在配置gin 路由的代码中,import如下几个包

    package router

    import (

        "fmt"

        "io"

        "cqi/dao"

        "cqi/operator/service"

        "cqi/utils/gin/midware"

        "github.com/gin-gonic/gin"

        swaggerFiles "github.com/swaggo/files"

        ginSwagger "github.com/swaggo/gin-swagger"

        "cqi/operator/docs" // docs is generated by Swag CLI, you have to import it.

    )

    最后的cqi/operator/docs应对应改为swag生成的docs目录

    同时在gin路由中增加如下代码:

    url := ginSwagger.URL(fmt.Sprintf("http://%s/swagger/doc.json", listen)) // The url pointing to API definition

    router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler, url))

    其中listen应对应服务部署的ip及端口。本质上其实是为服务增加了一个/swagger/*any类型的get接口,调用该接口则返回docs目录中的swagger.json。

    部署服务

    将服务部署到yAPI可以访问的环境上,启动。

    此时在浏览器中输入http://{host}:{port}/swagger/doc.json应该就能查看到接口返回了swagger.json的内容。

    配置yAPI swagger自动同步

    1.登录yAPI,创建好项目。

    2.选择项目,在上面的功能栏中选择“设置”

     3.选择“Swagger自动同步”,并在“项目的swagger json地址”中配置上http://{host}:{port}/swagger/doc.json这个访问接口

     4.点击“保存”,此时yAPI就会调用刚才配置的接口并获取swagger格式的文档,解析后在“接口”中展示。并且yAPI会自动同步。

     每次当你修改了api注释,重新生成swagger文档并将服务部署到对应的环境中时,yAPI就能够自动进行同步,并调整API

    展开全文
  • 光纤中间件,以使用Swagger 2.0自动生成RESTful API文档。 用法 开始使用它 将注释添加到您的API源代码中,。 使用以下方法下载 for Go: $ go get -u github.com/swaggo/swag/cmd/swag 在包含main.go文件的Go项目...
  • gin 中间件使用 Swagger 2.0 自动生成 RESTful API 文档。 用法 开始使用它 向您的 API 源代码添加注释,。 使用以下命令下载 for Go: $ go get -u github.com/swaggo/swag/cmd/swag 在包含main.go文件的 Go 项目...
  • Swagger注解生成插件

    2020-12-01 14:17:31
    swagger这个东西好用是好用但是增加了开发的工作量,一步到位就是在生成实体类时把这个注解也跟着生成。 方便是方便但是感觉swagger对项目的侵入性太强了,为了个API文档搞得项目到处都是这玩意。 还有就是非实体...

    swagger这个东西好用是好用但是增加了开发的工作量,一步到位就是在生成实体类时把这个注解也跟着生成。

    方便是方便但是感觉swagger对项目的侵入性太强了,为了个API文档搞得项目到处都是这玩意。

    还有就是非实体类,已有VO想要加这注解也就只能复制粘贴了

    windows alt+insert

    mac command+n

    效果

    下载地址:https://download.csdn.net/download/lanyanhua/13210905

    说些自己的想法:

    感觉swagger这个东西好用是好用但是呢,增加了开发人员的工作量,项目集成了swagger但很多人都不愿意写这个。

    还有一个问题swagger的展示是以后台contrller来区分的,这点对后台人员来说并没有什么影响。

    但对于前端来说就不太又好了,对于来说前端想要的应该是一个菜单结构的

    不知道市面上有没有这种东西,我觉得API文档单独搭建一个项目

    1. 接口信息来源:通过git源码读取doc注释进行生成相关的接口信息 ,分支之间互不冲突可以用来区分环境
    2. 在线调试:只需要配置项目路径加token这个可以和swagger一样swagger也需要配置token,swagger的路径就是swagger访问路径。这里只需要配置一下就好了,调用接口的是js在浏览器调用所以locahost也是可以的
    3. 配置菜单:接口信息进行配置菜单 可以配置一个web的和h5的,这些信息都在这个项目里配置完全不需要开发写代码

     

    展开全文
  • IDEA技巧:如何根据注释生成swagger注解

    千次阅读 多人点赞 2021-09-03 08:48:05
    如果你在使用swagger,那你知道swagger有一个自动生成swagger注解的神器么?

    相信大家在进行java项目开发,肯定会接触到swagger的,一款动态生成api文档的神奇,只需要在api上面加上注解,就可以生成文档,现在我简单介绍下swagger的快速入门,最后再说下如何根据注释快速生成这些烦人的注解。

    swagger日常操作

    引入swagger依赖

    <dependency>
    
    <groupId>io.springfox</groupId>
    
    <artifactId>springfox-swagger-ui</artifactId>
    
    <version>2.9.2</version>
    
    </dependency>
    
    
    
    <dependency>
    
    <groupId>io.springfox</groupId>
    
    <artifactId>springfox-swagger2</artifactId>
    
    <version>2.9.2</version>
    
    </dependency>
    

    开启swagger

    @Configuration
    
    @EnableSwagger2//开启Swagger2
    
    public class Swagger2Config {
    
    
    
    }
    

    swagger常用注解

    @Api:修饰整个类,描述Controller的作用
    
    @ApiOperation:描述一个类的一个方法,或者说一个接口
    
    @ApiModel:用对象来接收参数 ,修饰类
    
    @ApiModelProperty:用对象接收参数时,描述对象的一个字段
    
    @ApiResponse:HTTP响应其中1个描述
    
    @ApiResponses:HTTP响应整体描述,一般描述错误的响应
    
    @ApiIgnore:使用该注解忽略这个API
    
    @ApiError :发生错误返回的信息
    
    @ApiParam:单个参数描述
    
    @ApiImplicitParam:一个请求参数,用在方法上
    
    @ApiImplicitParams:多个请求参数
    

    相信大家入门swagger肯定是不难的,但是大家估计都有一个共同的痛点,就是每次开发一个新接口的时候,要加上一堆注解,特别难受,有没有一款插件能够自动生成这些注解呢?

    答案是有的。接下来我会给大家介绍下这款插件:Swagger Tools。

    直接打开idea的插件仓库:搜索Swagger Tools,就可以直接安装。
    在这里插入图片描述

    安装之后重启下idea。

    如何使用呢?
    使用方式很简单,只要在需要生成注解的文件右击,选择gēgenerate->swaggerannotation,就可以直接生成,是不是很简单
    在这里插入图片描述

    在这里插入图片描述

    本篇教程到此结束,后续会发布更多开发小技巧。

    关注微信公众号“AI码师”,领取2021面试资料和最新全套微服务教程
    在这里插入图片描述

    展开全文
  • 公司项目考虑使用swagger注释方式。简单看了一下,使用swagger生成文档要在方法上添加额外的注解来支持swagger文档生成。大概是这个样子 /** * @author: qiaofan * @date: 2019/6/4 18:07 * @version: 1.0 ...
  • Swagger显示注释

    2021-07-01 16:38:44
    2.完成之后会生成对应的XML文件 3.在Startup.cs 方法ConfigureServices中修改AddSwaggerGen内容 public void ConfigureServices(IServiceCollection services) { services.AddControllers(); services....
  • 根据字段上的doc注释生成swagger注解 @ApiModelProperty(value = "当前登录人名称")
  • /** * 自定义注释生成器 * Created by macro on 2018/4/26. */ public class CommentGenerator extends DefaultCommentGenerator { private boolean addRemarkComments = false; private static final String ...
  • 1、创建一个.NetCore WebApi项目 2、使用Nuget安装Swagger,安装的命令是: ...3、安装完Swagger插件之后,在Startup.cs文件中的ConfigureServices方法和Configure方法注册并使用Swagger服务。 在Con...
  • xml文档可以自动生成 勾选上xml文档文件 ... ///文档注释xml var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location); var xmlPath = Path.Combine(basePath, "AP...
  • * 根据property的值生成含有swagger apiModelProperty注解的属性 */ private CtField createField(ApiJsonProperty property, CtClass ctClass) throws NotFoundException, CannotCompileException { CtField ...
  • 1、file-settings-pluginss输入:swagger tools下载重启idea 2、在实体类里面快捷键:Alt+insert。选择第一个SwaggerAnnotation即可一键生成@ApiModelProperty
  • 使用装饰器自动生成swagger json文档 安装 npm install koa-swagger-decorator 贡献指南 请参考创建PR或发行前。 介绍 Koa Swagger装饰器 使用装饰器自动生成swagger json文档,添加对swagger定义的支持验证 基于 ...
  • springboot+mybatis-plus+swagger2全注释入门demo 有mysql数据库表 和访问的URL 是学习swagger2的好资料,只要有这个swagger2在不是难题了,及其易懂。
  • 在包含main.go文件的Go项目根文件夹中运行 , 将解析注释生成所需文件( docs文件夹和docs/doc.go )。 $ swag init 4,使用以下命令下载 : $ go get -u github.com/swaggo/http-swagger 并在您的代码中导入...
  • 使用swagger和yaml生成java类

    千次阅读 2021-03-09 05:40:03
    我想用maven插件swagger-codegen-...在这里我的pom.xml的配置文件:使用swagger和yaml生成java类io.swaggerswagger-codegen-maven-plugin2.2.3generate${basedir}/src/main/resources/swagger/project.yamljavas...
  • mybatis自动生成工具,带swagger2注释 以及时间格式处理
  • Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,同时swagger-ui还可以测试spring restful风格的接口功能...
  • -- swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> <exclu
  • 它将扫描您的项目源代码,提取具有特殊开头的注释,解析注释中的 swagger 代码并生成 swagger 文档。 包含文档、示例等。从那里开始 支持的语言 任何支持 c 风格的块注释的语言,即。 /* comments ... */ ...
  • 平时使用swagger都是通过正向来做,通过在代码中加注释等方式,生成一个swagger-ui的文档,这个页面将这个过程逆转,先生成文档,再反向生成api。 项目中实际使用的生成文档,加上注释并且去除相关敏感信息后,...
  • 编码实现2个springboot接口,让swagger自动生成接口文档 二、为什么要用swagger,它解决了什么问题? 随着sprnigboot、springcloud等微服务的流行,在微服务的设计下,小公司微服务小的几十,大公司大的几百上万的...
  • 技术栈 介绍 平时安装 swagger
  • 里面有我修改后的代码生成器,写了齐全的注释最好的入门demo,能直接生成swagger2注解的代码,主要属性已经提取成配置文件可以直接多表生成,restful风格让你的代码更优雅

空空如也

空空如也

1 2 3 4 5 ... 20
收藏数 7,823
精华内容 3,129
关键字:

swagger 根据注释生成