接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变成重中之重。接口文档固然重要，但是由于项目周期等原因后端人员经常出现无法及时更新，导致前端人员抱怨接口文档和实际情况不一致很多人员会抱怨别人写的接口文档不规范，不及时更新。当时当自己写的时候确实最烦去写接口文档。这种痛苦只有亲身经历才会牢记于心如果接口文档可以实时动态生成就不会出现上面问题Swagger可以完美的解决上面的问题
OpenAPI规范(OpenAPISpecificatio以前叫做Swagger规范，是RESTAPI的API描述格式。OpenAPI文件允许描述整个API，包括：
每个访问地址的类型。POST或GET每个操作的参数。包括输入输出参数认证方法连接信息，声明，使用团队和其他信息。
OpenAPI规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。OpenAPI规范为RESTfulAPI定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。然后，文档生成工具可以使用OpenAPI定义来显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例
Swagger简介
Swagger是一套围绕OpenAPI规范构建的开源工具，可以帮助设计，构建，记录和使用RESTAPISwagger工具包括的组件：
SwaggerEditor：基于浏览器编辑器，可以在里面编写OpenAPI规范。类似Markdown具有实时预览描述文件的功能。SwaggerUI：将OpenAPI规范呈现为交互式API文档。用可视化UI展示描述文件。SwaggerCodegen：将OpenAPI规范生成为服务器存根和客户端库。通过SwaggerCodegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。SwaggerInspector：和SwaggerUI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。SwaggerHub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到SwaggerHub中。在SwaggerHub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版使用Swagger，就是把相关的信息存储在它定义的描述文件里面，再通过维护这个描述文件可以去更新接口文档，以及生成各端代码
使用Swagger时如果碰见版本更新或迭代时，只需要更改Swagger的描述文件即可。但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。MartyPitt编写了一个基于Spring的组件swagger-springmvc。Spring-fox就是根据这个组件发展而来的全新项目。Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件。Spring-fox利用自身AOP特性，把Swagger集成进来，底层还是Swagger。但是使用起来确方便很多。所以在实际开发中，都是直接使用spring-fox。
Swagger用法
导入Spring-fox依赖在项目的poxml中导入Spring-fox依赖。其中springfox-swagger2是核心内容的封装。springfox-swagger-ui是对swagger-ui的封装。
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
Controller编写SpringBoot项目，项目中controller中包含一个Handler，测试项目，保证程序可以正确运行
@RestController
@RequestMapping('/people')
public class DemoController {
@RequestMapping('/getPeople')
public People getPeople(Long id, String name){
People peo = new People();
peo.setId(id);
peo.setName(name);
peo.setAddress('海淀');
return peo;
}
}
添加注解
在SpringBoot的启动类中添加@EnableSwagger2注解。添加此注解后表示对当前项目中全部控制器进行扫描。应用Swagger2
@SpringBootApplication
@EnableSwagger2
public class MyApp {
public static void main(String [] args){
SpringApplication.run(MyApp.class,args);
}
}
访问swagger-ui启动项目后在浏览器中输入http://ip:port/swagger-uhtml即可以访问到swagger-ui页面，在页面中可以可视化的进行操作项目中所有接口。
Swagger-UI使用
访问swagger-uhtml后可以在页面中看到所有需要生成接口文档的控制器名称每个控制器中间包含多所有控制器方法的各种访问方式。如果使用的是@RequestMapping进行映射，将显示下面的所有请求方式。如果使用@PostMapping将只有Post方式可以能访问，下面也就只显示Post的一个。点击某个请求方式中tryitout会出现界面要求输入的值。输入完成后点击Execute按钮下面会出现RequestURL已经不同状态码相应回来的结果
Swagger配置
可以在项目中创建SwaggerConfig，进行配置文档内容
配置基本信息
Docket：摘要对象，通过对象配置描述文件的信息。apiInfo:设置描述文件中info。参数类型ApiInfoselect():返回ApiSelectorBuilder对象，通过对象调用build()可以创建Docket对象ApiInfoBuilder：ApiInfo构建器
@Configuration
public class SwaggerConfig {
@Bean
public Docket getDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select() .build();
}
private ApiInfo swaggerDemoApiInfo(){
return new ApiInfoBuilder()
.contact(new Contact('Lanh', 'http://www.lanh.com', 'xxx@163.com'))
//文档标题
.title('这里是 Swagger 的标题')
//文档描述
.description('这里是 Swagger 的描述')
//文档版本
.version('1.0.0')
.build();
}
}
设置扫描的包
可以通过apis()方法设置哪个包中内容被扫描
@Bean
public Docket getDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(getApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage('com.lanh.controller'))
.build();
}
自定义注解设置不需要生成接口文档的方法
自定义注解注解名称随意
@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
public @interface NotIncludeSwagger { }
添加规则通过publicApiSelectorBuilderapis(Predicate
@Bean public Docket getDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.paths(allowPaths())
.apis(not(withMethodAnnotation(NotIncludeSwagger.class)))
.build();
}
添加NotIncludeSwagger注解在不需要生成接口文档的方法上面添加@NotIncludeSwagger注解后，该方法将不会被Swagger进行生成在接口文档中。
@NotIncludeSwagger
@RequestMapping('/getPeople2')
public People getPeople2(Integer id, String name, String address){
People peo = new People();
peo.setId(id);
peo.setName(name);
peo.setAddress(address);
return peo;
}
设置范围通过publicApiSelectorBuilderpaths(Predicateselector)可以设置满足什么样规则的url被生成接口文档。可以使用正则表达式进行匹配。下面例子中表示只有以/demo/开头的url才能被swagger生成接口文档。希望全部扫描可以使用paths(PathSelectors.any())
@Bean
public Docket getDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(swaggerDemoApiInfo())
.select()
.paths(allowPaths())
.build();
}
private Predicate allowPaths(){
return or(regex('/demo/.*') );
}
Swagger2常用注解
@Api是类上注解。控制整个类生成接口信息的内容tags：类的名称。可以有多个值，多个值表示多个副本description:描述，已过时
@RestController
@RequestMapping('/people')
@Api(tags = {'mydemo'},description = '描述')
public class DemoController {}
在swagger-uhtml中显示效果：
@ApiOperation写在方法上，对方法进行总体描述
value：接口描述notes：提示信息
@ApiOperation(value='接口描述',notes = '接口提示信息')
在swagger-ui中显示效果：
@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明
name：参数名称value：参数描述required：是否是必须
public People getPeople(Integer id, @ApiParam(value='姓名',required = true) String name, String address)
swagger-ui显示效果如下：
@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上
value：名称description：描述
@ApiModel(value = '人类',description = '描述')
public class People {}
swagger-uhtml效果展示：
@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容
value：描述name：重写属性名required：是否是必须的example：示例内容hidden：是否隐藏
@ApiModelProperty(value = '姓名',name = 'name',required = true,example = '张三 ')
private String name;
swagger-uhtml效果展示:
@ApiIgnore用于方法或类或参数上，表示这个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解。
@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
name：属性名value：描述required：是否是必须的paramType：属性类型dataType：数据类型
@PostMapping('/getPeople') @ApiImplicitParam(name = 'address',value = '地址',required = true,paramType = 'query',dataType = 'string')
public People getPeople(Integer id, @ApiParam(value='姓名',required = true) String name, String address){}
swagger-uhtml效果展示:
如果希望在方法上配置多个参数时，使用@ApiImplicitParams进行配置。示例如下：
@ApiImplicitParams(value={@ApiImplicitParam(name='id',value = '编号',required = true),@ApiImplicitParam(name='name',value = '姓名',required = true)})
文章为作者独立观点，不代表股票交易接口观点
股民评论