介绍
swagger是什么?
swagger-ui
使用swagger-ui
简单使用
swagger api注解
本文参考:
介绍
这里是一些介绍,如果想直接看如何使用,请直接跳过这部分。但如果有时间,就姑且看一下吧,这部分大概用时3分钟。
swagger是什么?
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。
目前的项目基本都是前后端分离,后端为前端提供接口的同时,还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新,这个时候有可能会忘记更新接口的说明文档,造成一些不必要的问题。
用人话说,swagger就是帮你写接口说明文档的。更具体地,可以看下面的图片,swagger官方建议使用下面的红字部分,这篇博客主要是记录如何,使用swagger自动生成Api文档的,所以只介绍swagger-ui,其他的…以后我用到会再整理。
swagger-ui
用来显示API文档的,不可编辑,会根据我们在代码中的设置来自动生成Api说明文档。生成的api文档如下,不好意思,长得不太像文档…但比文档更清楚对不对!对!
本文中的举例全部基于spring boot,如果不太熟悉构建请移步:spring教程(一),既然写道这里,介绍一下项目需要的环境
编译器:IntelliJ IDEA .3.5 x64框架:spring-boot-cli-1.4.3.RELEASE-binswagger版本:springfox-swagger2,2.9.2
使用swagger-ui
通过第一部分“简单使用”能够让你快速地使用swagger-ui来生成api文档,之后会详细地解释swagger-ui一些注解及使用方法。如果想要看swagger-ui用到的一些注解的详细使用方法、说明、及示例请移步第二部分“swagger api注解”。
简单使用
以下操作基于spring教程(一)的项目内容,项目结构如下,比较简单。
简单地使用swagger-ui只需要三步。
第一步,配置pom文件。在pom文件中引入swagger的相关依赖,在“<dependencies></dependencies>”中间添加下面的依赖。
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.8.0</version></dependency>
第二步,构建swagger配置类。我选择构建的位置是主目录下,目录并不会对运行结果产生影响,但整个项目只能有一个swagger配置类。配置类的代码如下,建议只粘贴类的代码部分,然后“alter+Enter”添加引入的包的部分。
import io.swagger.annotations.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;/*** Swagger使用的配置文件*/@Configuration@EnableSwagger2public class Swagger2Configuration {@Beanpublic Docket createRestApi(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).paths(PathSelectors.any()).build();}//基本信息的配置,信息会在api文档上显示private ApiInfo apiInfo(){return new ApiInfoBuilder().title("zg测试的接口文档").description("xx相关接口的文档").termsOfServiceUrl("http://localhost:8080/hello").version("1.0").build();}}
这里需要对第二步说明几点:
apiInfo:api基本信息的配置,信息会在api文档上显示,可有选择的填充,比如配置文档名称、项目版本号等apis:使用什么样的方式来扫描接口,RequestHandlerSelectors下共有五种方法可选。我们当前使用通过在类前添加@Api注解的方式,其他方法我们后续介绍。path:扫描接口的路径,PathSelectors下有四种方法,我们这里是全扫,其他方法我们后续介绍。
第三步,在接口文件中增加对应注解。代码如下,由于我们第二步选择扫描接口的方式是在类前添加@Api;@ApiOperation用于注明接口,value是接口的解释;@ApiParam注解函数里面的参数,name一般与参数名一致,value是解释,required是是否参数必须。
@Controller@Apipublic class HelloController {@ApiOperation(value = "你好")@ResponseBody@PostMapping("/hello")public String hello(@ApiParam(name="name",value="对话人",required=true)String name){return name+", hello";}}
上面操作都完成后,在浏览器中输入网址:http://localhost:8080/swagger-ui.html,我使用的接口是默认的8080,具体以自己项目的配置为准。
swagger api注解
这一部分除了,下面列出的注解外,还包括上面所介绍的RequestHandlerSelectors和PathSelectors的几种方法及含义。
@Api: 用于类,标识这个类是swagger的资源@ApiIgnore: 用于类,忽略该 Controller,指不对当前类做扫描@ApiOperation: 用于方法,描述 Controller类中的 method接口@ApiParam: 用于参数,单个参数描述,与 @ApiImplicitParam不同的是,他是写在参数左侧的。如( @ApiParam(name="username",value="用户名")Stringusername)@ApiModel: 用于类,表示对类进行说明,用于参数用实体类接收@ApiProperty:用于方法,字段,表示对model属性的说明或者数据操作更改@ApiImplicitParam: 用于方法,表示单独的请求参数@ApiImplicitParams: 用于方法,包含多个 @ApiImplicitParam@ApiResponse: 用于方法,描述单个出参信息@ApiResponses: 用于方法,包含多个@ApiResponse@ApiError: 用于方法,接口错误所返回的信息
本文参考:
超详细 swagger api注解spring boot项目中使用swagger25分钟了解swagger官方Class RequestHandlerSelectors文档如果觉得《超详细!使用swagger自动生成Api文档(swagger-ui)》对你有帮助,请点赞、收藏,并留下你的观点哦!