精华内容
参与话题
问答
  • 1.学会分布式集群架构的设计思想及部署策略 2.掌握项目中第三方接入技术的实战应用 3.掌握使用Nexus搭建Maven私服 4.掌握如何基于微服技术Spring boot升级电商爱旅行项目
  • 5分钟了解swagger

    万次阅读 多人点赞 2017-08-27 20:47:06
    API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。其他API文档工具没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confl

    随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。
    前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架。

    其他API文档工具

    没有API文档工具之前,大家都是手写API文档的,在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。

    书写API文档的工具有很多,但是能称之为“框架”的,估计也只有swagger了。
    在此先介绍一款其他的API文档工具,叫rap,这玩意儿用一句话就能概括:解放生产力,代替手写API的web工具。
    RAP写起来确实比手写文档要快,看看图就知道:
    可以选择某个项目,写针对某个项目的API
    这里写图片描述

    请看,可以填写请求和相应的字段
    这里写图片描述

    还可以选择字段对应的类型
    这里写图片描述

    类似的API文档工具网上还有很多,但是能拿上台面的,不多。RAP是由阿里开发的,整个阿里都在用,还不错。github地址为:https://github.com/thx/RAP
    当然咯,rap不可能只有线上版本,肯定可以部署到私服上。
    https://github.com/thx/RAP/wiki/deploy_manual_cn

    swagger

    rap挺好的,但是和swagger比起来有点轻量。
    先看看swagger的生态使用图:

    这里写图片描述
    其中,红颜色的是swaggger官网方推荐的。

    下面再细看看swagger的生态的具体内容:

    swagger-ui

    这玩意儿从名字就能看出来,用来显示API文档的。和rap不同的是,它不可以编辑。

    这里写图片描述

    点击某个详细API的可以试。

    这里写图片描述

    swagger-editor

    就是一个在线编辑文档说明文件(swagger.json或swagger.yaml文件)的工具,以方便生态中的其他小工具(swagger-ui)等使用。
    左边编辑,右边立马就显示出编辑内容来。
    这里写图片描述

    编辑swagger说明文件使用的是yaml语法具体的内容可以去官网查看。

    各种语言版本的根据annotation或者注释生成swagger说明文档的工具

    目前最流行的做法,就是在代码注释中写上swagger相关的注释,然后,利用小工具生成swagger.json或者swagger.yaml文件。

    目前官方没有推出。github上各种语言各种框架各种有,可以自己搜吧搜吧,这里只说一个php相关的。
    swagger-php :https://github.com/zircote/swagger-php

    swagger-validator

    这个小工具是用来校验生成的文档说明文件是否符合语法规定的。用法非常简单,只需url地址栏,根路径下加上一个参数url,参数内容是放swagger说明文件的地址。即可校验。
    例如:
    这里写图片描述
    docker hub地址为:https://hub.docker.com/r/swaggerapi/swagger-validator/
    可以pull下镜像来自己玩玩。

    swagger-codegen

    代码生成器,脚手架。可以根据swagger.json或者swagger.yml文件生成指定的计算机语言指定框架的代码。
    有一定用处,Java系用的挺多。工业上应该不咋用。

    mock server

    这个目前还没有找到很合适的mock工具,包括rap也好,其他API文档工具也好,都做的不够完善,大多就是根据说明文件,例如swagger.json等生成一些死的静态的mock数据,不能够根据限定条件:例如“只能是数字,必传”等做出合理的回应。

    更多精彩内容,请关注我的微信公众号 互联网技术窝 或者加微信共同探讨交流:

    展开全文
  • swagger 介绍及两种使用方法

    万次阅读 多人点赞 2018-04-26 15:13:30
    一:swagger是什么? 1、是一款让你更好的书写API文档的规范且完整框架。 2、提供描述、生产、消费和可视化RESTful Web Service。 3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库...

    一:swagger是什么?

    1、是一款让你更好的书写API文档的规范且完整框架。

    2、提供描述、生产、消费和可视化RESTful Web Service。

    3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

    方法一:使用第三方依赖(最简单的方法)

    1、在pom.xml文件中添加第三方swagger依赖()

    	<dependency>
    		<groupId>com.spring4all</groupId>
    		<artifactId>swagger-spring-boot-starter</artifactId>
    		<version>1.7.0.RELEASE</version>
    	</dependency>
    

    2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解,就可以直接使用啦。
    3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目,里面有详细的讲解。

    方法二:使用官方依赖

    1、在pom.xml文件中添加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>
    
    第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
    2、swagger的configuration

    需要特别注意的是swagger scan base package,这是扫描注解的配置,即你的API接口位置。

    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 Swagger2 {
    
            @Bean
            public Docket createRestApi() {
                return new Docket(DocumentationType.SWAGGER_2)
                        .apiInfo(apiInfo())
                        .select()
                        .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                        .paths(PathSelectors.any())
                        .build();
            }
    
            private ApiInfo apiInfo() {
                return new ApiInfoBuilder()
                        .title("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台 APIs")
                        .description("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台")
                        .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin")
                        .contact("程序猿")
                        .version("1.0")
                        .build();
            }
    
        }
    

    三、具体使用

    1、在API上做一些声明
    //本controller的功能描述
    @Api(value = "pet", description = "the pet API")
    public interface PetApi {
    
        //option的value的内容是这个method的描述,notes是详细描述,response是最终返回的json model。其他可以忽略
        @ApiOperation(value = "Add a new pet to the store", notes = "", response = Void.class, authorizations = {
            @Authorization(value = "petstore_auth", scopes = {
                @AuthorizationScope(scope = "write:pets", description = "modify pets in your account"),
                @AuthorizationScope(scope = "read:pets", description = "read your pets")
                })
        }, tags={ "pet", })
    
        //这里是显示你可能返回的http状态,以及原因。比如404 not found, 303 see other
        @ApiResponses(value = { 
            @ApiResponse(code = 405, message = "Invalid input", response = Void.class) })
        @RequestMapping(value = "/pet",
            produces = { "application/xml", "application/json" }, 
            consumes = { "application/json", "application/xml" },
            method = RequestMethod.POST)
        ResponseEntity<Void> addPet(
        //这里是针对每个参数的描述
        @ApiParam(value = "Pet object that needs to be added to the store" ,required=true ) @RequestBody Pet body);
    
    2、设定访问API doc的路由

    在配置文件中,application.yml中声明:

    springfox.documentation.swagger.v2.path: /api-docs
    

    这个path就是json的访问request mapping.可以自定义,防止与自身代码冲突。

    API doc的显示路由是:http://localhost:8080/swagger-ui.html

    如果项目是一个webservice,通常设定home / 指向这里:

    @Controller
    public class HomeController {
    
        @RequestMapping(value = "/swagger")
        public String index() {
            System.out.println("swagger-ui.html");
            return "redirect:swagger-ui.html";
        }
    }
    

    四:swagger的常用API

    1、api标记

    Api 用在类上,说明该类的作用。可以标记一个Controller类做为swagger 文档资源,使用方式:

    @Api(value = "/user", description = "Operations about user")

    在这里插入图片描述

    2、ApiOperation标记

    ApiOperation:用在方法上,说明方法的作用,每一个url资源的定义,使用方式:

    @ApiOperation(
              value = "Find purchase order by ID",
              notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
              response = Order,
              tags = {"Pet Store"})
    

    3、ApiParam标记

    ApiParam请求属性,使用方式:

    public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)
    

    4、ApiResponse

    ApiResponse:响应配置,使用方式:
    @ApiResponse(code = 400, message = "Invalid user supplied")

    5、ApiResponses

    ApiResponses:响应集配置,使用方式:
    @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

    6、ResponseHeader

    响应头设置,使用方法
    @ResponseHeader(name="head1",description="response head conf")

    展开全文
  • Swagger 实战教程

    千人学习 2020-02-20 20:39:07
    Swagger视频培训教程,该课程详细讲解Swagger如何使用,其中包括SwaggerSwagger UI、 Springfox简介,三者之间的联系;Spring Boot 中快速集成Swagger;Spring MVC 中快速集成SwaggerSwagger + Springfox快速...
  • swagger使用和教程

    万次阅读 2018-09-27 11:34:58
    由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象...

    由于Spring Boot能够快速开发、便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API。而我们构建RESTful API的目的通常都是由于多终端的原因,这些终端会共用很多底层业务逻辑,因此我们会抽象出这样一层来同时服务于多个移动端或者Web前端。

    这样一来,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发或是Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

    • 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳。
    • 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象。

    为了解决上面这样的问题,本文将介绍RESTful API的重磅好伙伴Swagger2,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API。具体效果如下图所示:

    alt=alt=

    下面来具体介绍,如果在Spring Boot中使用Swagger2。首先,我们需要一个Spring Boot实现的RESTful API工程,若您没有做过这类内容,建议先阅读
    Spring Boot构建一个较为复杂的RESTful APIs和单元测试

    下面的内容我们会以教程样例中的Chapter3-1-1进行下面的实验(Chpater3-1-5是我们的结果工程,亦可参考)。

    添加Swagger2依赖

    pom.xml中加入Swagger2的依赖

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

    创建Swagger2配置类

    Application.java同级创建Swagger2的配置类Swagger2

    @Configuration
    @EnableSwagger2
    public class Swagger2 {
    
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.didispace.web"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("Spring Boot中使用Swagger2构建RESTful APIs")
                    .description("更多Spring Boot相关文章请关注:http://blog.didispace.com/")
                    .termsOfServiceUrl("http://blog.didispace.com/")
                    .contact("程序猿DD")
                    .version("1.0")
                    .build();
        }
    
    }
    

    如上代码所示,通过@Configuration注解,让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

    再通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现,本例采用指定扫描的包路径来定义,Swagger会扫描该包下所有Controller定义的API,并产生文档内容(除了被@ApiIgnore指定的请求)。

    添加文档内容

    在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams@ApiImplicitParam注解来给参数增加说明。

    @RestController
    @RequestMapping(value="/users")     // 通过这里配置使下面的映射都在/users下,可去除
    public class UserController {
    
        static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());
    
        @ApiOperation(value="获取用户列表", notes="")
        @RequestMapping(value={""}, method=RequestMethod.GET)
        public List<User> getUserList() {
            List<User> r = new ArrayList<User>(users.values());
            return r;
        }
    
        @ApiOperation(value="创建用户", notes="根据User对象创建用户")
        @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
        @RequestMapping(value="", method=RequestMethod.POST)
        public String postUser(@RequestBody User user) {
            users.put(user.getId(), user);
            return "success";
        }
    
        @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
        @RequestMapping(value="/{id}", method=RequestMethod.GET)
        public User getUser(@PathVariable Long id) {
            return users.get(id);
        }
    
        @ApiOperation(value="更新用户详细信息", notes="根据url的id来指定更新对象,并根据传过来的user信息来更新用户详细信息")
        @ApiImplicitParams({
                @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long"),
                @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
        })
        @RequestMapping(value="/{id}", method=RequestMethod.PUT)
        public String putUser(@PathVariable Long id, @RequestBody User user) {
            User u = users.get(id);
            u.setName(user.getName());
            u.setAge(user.getAge());
            users.put(id, u);
            return "success";
        }
    
        @ApiOperation(value="删除用户", notes="根据url的id来指定删除对象")
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
        @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
        public String deleteUser(@PathVariable Long id) {
            users.remove(id);
            return "success";
        }
    
    }
    

    完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
    。就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求,以POST类型的/users请求为例,可找到上述代码中我们配置的Notes信息以及参数user的描述信息,如下图所示。

    altalt

    API文档访问与调试

    在上图请求的页面中,我们看到user的Value是个输入框?是的,Swagger除了查看接口功能外,还提供了调试测试功能,我们可以点击上图中右侧的Model Schema(黄色区域:它指明了User的数据结构),此时Value中就有了user对象的模板,我们只需要稍适修改,点击下方“Try it out!”按钮,即可完成了一次请求调用!

    此时,你也可以通过几个GET请求来验证之前的POST请求是否正确。

    相比为这些接口编写文档的工作,我们增加的配置内容是非常少而且精简的,对于原有代码的侵入也在忍受范围之内。因此,在构建RESTful API的同时,加入swagger来对API文档进行管理,是个不错的选择。

    展开全文
  • swagger详解(全)

    2020-04-07 00:56:58
    Swagger 问题 在前后端分离时代一个项目的制作通过两个团队共同完成 【后端团队】后端控制层、服务层、数据访问层 【前端团队】前端控制层,视图层 前后端通过API交互,两端相对独立且松耦合 由此产生的问题是,...

    Swagger

    问题

    在前后端分离时代一个项目的制作通过两个团队共同完成

    【后端团队】后端控制层、服务层、数据访问层

    【前端团队】前端控制层,视图层

    前后端通过API交互,两端相对独立且松耦合

    由此产生的问题是,前端人员和后端人员无法做到"即时协商、尽早解决",前后端集成联调时,最终
    导致问题集中爆发。

    解决方案首先指定schema【计划的提纲】,实时更新最新API,降低集成的风险。

    早些年通过指定word计划文档

    前后端分离后,前端测试后端解耦通过postman软件工具。后端提供解耦,需要实时更新最新的消息及改动

    接着出现的解决方案就是swagger

    初步使用

    起步:创建springboot工程、引入web模块、编写一个hello请求

    1. 引入srpingfox依赖

      <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
          <dependency>
              <groupId>io.springfox</groupId>
              <artifactId>springfox-swagger2</artifactId>
              <version>2.9.2</version>
          </dependency>
      
          <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
          <dependency>
              <groupId>io.springfox</groupId>
              <artifactId>springfox-swagger-ui</artifactId>
              <version>2.9.2</version>
          </dependency>
      

      [注]
      1.使用swagger要求jdk1.8及以上,否则swagger2不能运行
      2.springboot集成swagger需要引入两个包即以上两个

    2. 配置Swagger

      @Configuration
      @EnableSwagger2  //开启swagger2
      public class SwaggerConfig {
      }
      

      [注]
      1.此时swagger其实已经可以访问了,不用任何配置

    3. 运行测试

      访问:http://localhost:8080/swagger-ui.html
      

      效果图示例
      在这里插入图片描述

    进阶:简单使用

    配置swagger封面信息

    @Bean
    public Docket docket(){
    	   return new Docket(DocumentationType.SWAGGER_2)
    	           .apiInfo(apiInfo());
    }
    
    private ApiInfo apiInfo(){
    	
    	   //作者信息
    	   Contact contact = new Contact("Ferao", "https://blog.csdn.net/qq_21561501", "928971634@qq.com");
    	
    	   return new ApiInfo(
    	           "Ferao的swaggerAPI文档",
    	           "11",
    	           "v1.0",
    	           "https://blog.csdn.net/qq_21561501",
    	           contact,
    	           "Apache2.0",
    	           "https://blog.csdn.net/qq_21561501",
    	           new ArrayList()
    	   );
    }
    

    [注]
    1.swagger实例bean是Docket,所以通过配置Docket实例来配置Swagger
    2.apiInfo()是配置文档的基础信息
    效果图示例 在这里插入图片描述

    进阶配置:扫描接口

    @Bean
    public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    //是否启动swagger 如果是false则不能在浏览器中使用
                    .enable(true)
                    .select()
                    //RequestHandlerSelectors. 配置要扫描的方式
                    //basePackage():指定要扫描的包
                    //any():扫描全部
                    //none():不扫描
                    //withClassAnnotation():扫描类上的注解,参数是一个注解的反射对象
                    //withMethodAnnotation():扫描方法上的注解
                    .apis(RequestHandlerSelectors.basePackage("com.ferao.controller"))
                    //.paths() .过滤URL
                    //any() 任何请求都扫描
                    //none() 任何请求都不扫描
                    //ant()	通过ant控制
                    //regex() 通过正则表达式控制
                    .paths(PathSelectors.ant("/ferao/**"))
                    .build();
     }
    

    需求:老板只希望swagger在生产环境中使用,在发布的时候不使用

    分析:
    1.判断是不是生产环境 flag=false
    2.注入enable(flag)

    @Configuration
    @EnableSwagger2  //开启swagger2
    public class SwaggerConfig {
    
        //配置swagger的Docket的bean实例
        @Bean
        public Docket docket(Environment environment){
    
            //设置要显示的swagger环境
            Profiles profiles = Profiles.of("dev", "test");
            //通过environment.acceptsProfiles判断是否处于自己设定的环境中
            boolean flag = environment.acceptsProfiles(profiles);
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName("Ferao-group")
                    .apiInfo(apiInfo())
                    .enable(flag)
                    .select()
                    //配置要扫描的接口
                    .apis(RequestHandlerSelectors.basePackage("com.ferao.controller"))
                    .paths(PathSelectors.ant("/users/**"))
                    .build();
        }
    
        //配置swagger信息=apiInfo
        private ApiInfo apiInfo(){
    
            //作者信息
            Contact contact = new Contact("Ferao", "https://blog.csdn.net/qq_21561501", "928971634@qq.com");
    
            return new ApiInfo(
                    "Ferao的swaggerAPI文档",
                    "11",
                    "v1.0",
                    "https://blog.csdn.net/qq_21561501",
                    contact,
                    "Apache2.0",
                    "https://blog.csdn.net/qq_21561501",
                    new ArrayList()
            );
        }
    }
    

    进阶配置:API分组

     @Bean
        public Docket docket1(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
        }
    @Bean
        public Docket docket1(){
            return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
        }
    

    效果图示例
    在这里插入图片描述

    进阶配置:实体类描述

    1. 只要接口中返回值存在实体类,就会被swagger扫描

    2. swagger页面给实体类Moel加注释

      @Data
      @NoArgsConstructor
      @AllArgsConstructor
      @ApiModel("User实体类")
      public class User {
      
          @ApiModelProperty("用户名")
          private String username;
          @ApiModelProperty("用户年龄")
          private int age;
          @ApiModelProperty("服务端设置")
          private Date date;
      }
      

      效果图示例
      在这里插入图片描述

    请求接口名称描述

    @ApiOperation(value = "1.根据全局变量获得author")
    	   @GetMapping("/user")
    	   public String getUsers(ModelMap modelMap){
    	       System.out.println(modelMap.get("author"));
    	       return "User-Messege";
    	   }
    

    效果图示例
    在这里插入图片描述

    请求接口参数描述

    @ApiOperation(value = "1.根据全局变量获得author")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query", dataType = "String")
    })
    @GetMapping("/user")
    public String getUsers(String name){
        return "User-Messege";
    }
    

    效果图示例

    在这里插入图片描述

    Responses返回类型描述

    @ApiOperation(value = "1.根据全局变量获得author") 
    @ApiImplicitParams({
         @ApiImplicitParams({
                @ApiImplicitParam(name = "name", value = "名称", required = true, paramType = "query", dataType = "String")
        })
    })
    @ApiResponses({
            @ApiResponse(code=200,message="请求成功"),
            @ApiResponse(code=500,message="系统异常")
    })
    @GetMapping("/user")
    public String getUsers(String name){
        return "User-Messege";
    }
    

    [注]
    paramType=“body” 代表参数应该放在请求的什么地方:
    header–>放在请求头。请求参数的获取:@RequestHeader(代码中接收注解)
    query–>用于get请求的参数拼接。请求参数的获取:@RequestParam(代码中接收注解)
    path(用于restful接口)–>请求参数的获取:@PathVariable(代码中接收注解)
    body–>放在请求体。请求参数的获取:@RequestBody(代码中接收注解)
    form(不常用)
    dataType=“int” 代表请求参数类型为int类型,当然也可以是Map、User、String等;

    总结

    接口文档实时更新解决了开发者之间即时交互作用很重要

    注意在正式发布的时候,关闭swagger,出于安全考虑。而且节省运行的内存

    展开全文
  • OpenAPI规范3-Swagger2

    万次阅读 2017-12-18 00:14:38
     Info:之前使用的swagger是1.0版本,现在想将该规范使用到现在的项目中时,发现已经是基于OpenAPI 3的2.0版本,并且可以比1.0更方便的集成使用(1.0版本需要将GitHub中的swagger的web部分拷贝到项目下,现只需要...
  • Swagger Specification 是一种 API Specification(API 规范),2015 年,SmartBear Software 将 Swagger Specification 捐赠给 Linux Foundation,并改称为 OpenAPI Specification,简称(OAS)。SmartBear
  • swagger家族 Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的...
  • 1 Swagger介绍 OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在github...
  • Swagger简介

    万次阅读 多人点赞 2015-03-22 21:09:05
    前言 Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。...Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视...
  • Swagger使用指南

    万次阅读 多人点赞 2018-06-03 11:39:09
    1:认识Swagger Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端...
  • Swagger教程

    万次阅读 多人点赞 2018-08-15 20:16:35
    Swagger搭建Restful接口教程一 一、前言  Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件,随着现在许多公司实现了前后端分离,swagger越来越受欢迎了。  博主之前在网上查看相关博客的时候,...
  • Swagger 常用注解使用详解

    万次阅读 多人点赞 2018-03-16 09:18:24
    在集成了swagger2后,找了半天的原因,发现使用@ApiImplicitParam这个注解可以解决这个问题。对应下面的参数。所以我们可以使用这个注解来解决我们所遇到的参考为空的问题。而且已经集成了swagger2,所以我们尽量...
  • 首先安装包 Install-Package Swashbuckle.AspNetCore public void ConfigureServices(IServiceCollection services) { services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo ...
  • Swagger

    千次阅读 2019-05-31 11:22:29
    1.什么是Swagger OpenAPI规范(OpenAPI Specification 简称OAS)是Linux基金会的一个项目,试图通过定义一种用来描述API格式或API定义的语言,来规范RESTful服务开发过程,目前版本是V3.0,并且已经发布并开源在...
  • swagger

    千次阅读 2019-06-11 11:12:31
    本文作者:小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119  实际项目中非常需要写文档,提高Java...一:Swagger介绍Swagger是当前最好用的Restful API文档生成的...
  • swagger

    2019-10-28 18:10:41
    在Java类中添加Swagger的注解即可生成Swagger接口,常用Swagger注解如下: @Api:修饰整个类,描述Controller的作用 @ApiOperation:描述一个类的一个方法,或者说一个接口 @ApiParam:单个参数描述 @ApiModel:...
  • Swagger

    千次阅读 2017-04-18 16:27:20
    Swagger 是一个用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 让部署管理和使用功能强大的API从未如此简单。 下面会从基本原理、如何使用(基于spring-mvc)、常用注解 、源码分析四个部分进行分析...
  • swagger2 注解说明 ( @ApiImplicitParams )

    万次阅读 多人点赞 2018-10-17 12:25:36
    @Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、...

空空如也

1 2 3 4 5 ... 20
收藏数 61,109
精华内容 24,443
关键字:

Swagger