Swagger2的使用

这不做基本介绍了,新手只需要知道是一个接口文档规范,按照它的规范(注解形式)能自动生成web形式接口文档,通过url都前后端都可以访问,方便数据交互就可以了,重点在于使用

spring boot 中swagger2的依赖

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

spring boot已经整合了swagger,就是springfox,其作用就是生成接口文档,简化开发.
还有一个依赖是

     <dependency><groupId>com.mangofactory</groupId><artifactId>swagger-springmvc</artifactId><version>0.9.5</version></dependency>

springfox就是由swagger-spingmvc发展而来,前者自然比后者更强大更适用.

在这里只是实用的例子,基本开发够用,想深入,去官网

springfox官网链接

导入依赖后,首先要做的就是写一个配置类(复制粘贴下方代码,日常开发基本可以满足,要求比较高的话可查官网增加配置)

import io.swagger.annotations.ApiOperation;
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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.HashSet;
import java.util.Set;@Configuration
@EnableSwagger2
public class SwaggerConfiguration {@Beanpublic Docket createRestApi() {Set<String> producesList = new HashSet<>();producesList.add("application/json");return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).produces(producesList).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();}//文档信息说明和个人信息配置private ApiInfo apiInfo() {return new ApiInfoBuilder().title("我的swagger").description("我的的描述").contact(new Contact("我的邮箱", "", "xxxxxxxx@163.com")).version("1.0").build();}
}

写完配置类后,启动application就可以访问swagger web页面了,
swagger web页面地址(接口文档):http://localhost:8080/swagger-ui.html
我们的接口文档的雏形也就出来了 apiInfo()方法中定义的内容,可对比下图

接口文档雏形已经有了,剩下的就是接口实际对接参数了.

@Api(value = "Api value啊", tags = {"Api tags啊"})
@RestController
@RequestMapping("/account")
public class AccountController {}

上方是一个controller
@Api注解是swagger注解,作用就是对于当前的controller做一个说明

下方是一个controller中的一个方法

    @ApiOperation(value = "ApiOperation Value啊", notes = "ApiOperation Note啊")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户编号", required = true,dataType = "long"),@ApiImplicitParam(name = "name", value = "用户名", required = false)})@RequestMapping(value = "/swagger", method = RequestMethod.GET)public String swaggerTest(@RequestParam("id") Long id, @RequestParam("name") String name) {return name + ":" + id;}

@ApiOperation 是非常重要的一个注解,作用于方法上,用来做方法的说明
比如@ApiOperation(values = “获取用户信息”) 前端很容易就可以知道,获取用户信息要调用这个接口.其中的notes是注意事项,也可以理解成描述,可以将请求参数等信息直接用文字写到里面,虽然不正式,但是如果能说明白,也可以不需要再用
@ApiImplicitParam @ApiImplicitParams @ApiParam等注解再对参数进行说明,偷懒时候可以这么干.

@ApiImplicitParams相当于 @ApiImplicitParam集合
@ApiImplicitParam是对入参进行说明,但是只是对单个参数说明,比如long id
就用@ApiImplicitParam(name = “id”,value=“用户编号”, required = true,dataType = “long”) name 必须等于参数名,value是参数说明.还有一个参数是String name 就再用一个注解去说明.但是如果是一个自动封装的Bean对象,比如Test test 这个注解就不能说明出Test对象中每一个属性了,也就是@ApiImplicitParam注解只能说明当前对象,但是对向前对象内部结构无法说明,后面会讲解.

@ApiParam注解作用基本等同于@ApiImplicitParam

     @ApiOperation(value = "swagger啊", notes = "swagger1注意事项")@RequestMapping(value = "/swagger1", method = RequestMethod.GET)public String swaggerTest1(@RequestParam("id")  @ApiParam(name="用户编号",value="用户号编号说明",required=true)Long id,@RequestParam("name")  @ApiParam(name="用户名字",value="用户名字说明",required=true) String name) {return name + ":" + id;}
123456

它作用在参数上,也是对参数的说明,@ApiParam中name可以不是参数名,value是对参数的描述,所以选择用@ApiParam还是@ApiImplicitParam 可以自己决定,不过我比较推荐,基本数据类型用@ApiImplicitParam, Bean类型用@ApiParam.

最后一个方法

    @ApiOperation(value = "swagger2啊", notes = "swagger2注意事项")@RequestMapping(value = "/swagger2", method = RequestMethod.POST)public String swaggerTest2(@RequestBody @ApiParam(name="用户对象",value="用户对象说明",required=true) Test test) {return test.getString2() + ":" + test.getString1();}

这样子只能对于test这个对象进行说明,但是内部属性,没有办法说明,因为我们是json自动转对象,所以有必要说明下test中每个字段,前端也好传参,要说明自定义对象,需要用@ApiModel 和@ApiModelProperty 注解

@ApiModel(value="test对象",description="test测试")
public class Test {@ApiModelProperty(name = "string1",value = "第一个string",dataType = "String",example = "string1example",required = true)private String string1;@ApiModelProperty(name = "string2",value = "第二个string",dataType = "String",example = "string2example",required = false)private String string2;///getter setter toString}

@ApiModel注解作用于类上,是对类的说明,@ApiModelProperty是对属性的说明

以上就是springfox(swagger)的基本使用,开发中用的最多的几个注解已经说明了,至于其他的注解我现在基本不用,所以不再说明.要学习springfox,就多写几个接口,用几次注解,熟悉一下web 页面,很快就可以学会~

Swagger2的使用相关推荐

导出swagger2生成的文档
百度了好多篇用法,没法用.特此记录一下一.下载项目下载https://github.com/Swagger2Markup/spring-swagger2markup-demo下的项目,保存,注意文 ...
Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
springMVC swagger2
参考地址:https://www.cnblogs.com/exmyth/p/7183753.html https://blog.csdn.net/programmer_sean/article/det ...
SpringBoot之集成swagger2
maven配置 <dependency><groupId>io.springfox</groupId><artifactId>springfox-swa ...
SpringBoot+Mybatis+Swagger2环境搭建
点击上方"方志朋",选择"设为星标" 回复"666"获取新整理的面试资料作者:calebman https://www.jianshu.c ...
SpringBoot第十一篇：springboot集成swagger2，构建优雅的Restful API
swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容易构建restful风 ...
Springboot swagger2教程
swagger2教程 swagger,中文"拽"的意思.它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试.另外swagger很容 ...
springboot集成swagger2测试接口
springboot集成swagger2测试接口 1.需要的依赖 2.开始编写一个swagger2 3.演示效果图片 1.需要的依赖 <dependency><groupId> ...
springboot集成swagger2多模块中文配置详细步骤，解决集成mybatis或mybatis-plus无法正常使用问题
springboot集成swagger2多模块中文配置详细步骤,解决集成mybatis或mybatis-plus无法正常使用问题参考文章: (1)springboot集成swagger2多模块中文配 ...
Swagger2异常:Illegal DefaultValue null for parameter type integer java
Swagger2异常:Illegal DefaultValue null for parameter type integer java 参考文章: (1)Swagger2异常:Illegal Def ...

Swagger2的使用

Swagger2的使用相关推荐

最新文章

热门文章