Swagger的简单介绍

Swagger是什么

官方的介绍是 A POWERFUL INTERFACE TO YOUR API。

通过Swagger提供的相关tools可以很直观的在网页上浏览你的API、测试API、甚至通过解析Swagger definitions（一个YAML or JSON格式的文档），直接自动生成相关代码（swagger-codegen）。个人理解Swagger的核心就是Swagger definitions，相关工具可以（Swagger Core、Swagger Editor）生成Swagger definitions，（Swagger UI、Swagger Editor）解析Swagger definitions生成UI界面。

为什么要用Swagger

工具从来都是为了提高效率而产生的，想想从前光写个API文档都要花好些时间，而且其中还会出现理解上的偏差，需要前后端反复沟通确认，不仅浪费了时间还没有什么效率。通过使用Swagger，我们既可以用它来作为API的文档，也可以用来测试API，前端 or 客户端的同学通过对各个API的点击可以实时的看到返回结果，节约了大量的沟通时间，极大的提高了开发效率。

怎么用

  • 第一种,定义YAML文件，然后可以生成各种语言的代码框架.
  • 第二种,swagger有各种语言的插件，可以通过配置及少量代码，生成接口文档及测试界面。

我们不用再做：1、到Wiki中更新接口文档；2、Postman形式的测试；3、Curl形式的测试

Spring MVC上使用Swagger的简例子

创建SpringMVC工程

在pom文件中增加 Swagger相关依赖包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 <dependency>  
    <groupId>io.swagger</groupId>  
    <artifactId>swagger-core</artifactId>  
    <version>1.5.8</version>  
</dependency>  
<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>

增加配置文件

SwaggerConfiguration.java

1
2
3
4
5
6
7
8
9
10
11
12
@Configuration  
@EnableSwagger2  
public class SwaggerConfiguration {  
    @Bean  
    public Docket api() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .select()  
                .apis(RequestHandlerSelectors.any())  
                .paths(PathSelectors.any())  
                .build();  
    }  
}

SwaggerWebMvcConfigurerAdapter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
@Configuration  
@EnableWebMvc  
@ComponentScan(basePackages = "com.xx.yy.controller")  
public class SwaggerWebMvcConfigurerAdapter extends WebMvcConfigurerAdapter {  
   
    @Bean  
    public ViewResolver viewResolver() {  
        InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();  
        viewResolver.setViewClass(JstlView.class);  
        viewResolver.setPrefix("/WEB-INF/views/");  
        viewResolver.setSuffix(".jsp");  
        return viewResolver;  
    }  
   
    @Bean  
    public MessageSource messageSource() {  
        ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();  
        messageSource.setBasename("messages");  
        return messageSource;  
    }  
    @Override  
    public void addResourceHandlers(ResourceHandlerRegistry registry) {  
        super.addResourceHandlers(registry);  
        registry.addResourceHandler("swagger-ui.html")  
                .addResourceLocations("classpath:/META-INF/resources/");  
        registry.addResourceHandler("/webjars/**")  
                .addResourceLocations("classpath:/META-INF/resources/webjars/");  
    }  
    @Override  
    public void configureDefaultServletHandling(DefaultServletHandlerConfigurer configurer) {  
        configurer.enable();  
    }  
}

配置Controller

1
2
3
4
5
6
7
8
9
@Controller
public class MainController {
		@ResponseBody
		@RequestMapping(value = "/helloworld", method = RequestMethod.GET)
		@ApiOperation(nickname = "swagger-helloworld", value = "Swagger的世界", notes = "测试HelloWorld")
		public String helloWorld(@ApiParam(value = "昵称") @RequestParam String nickname) {
			return "Hello world, " + nickname;
		}
}

运行

运行项目后
进入http://localhost:8080/<path>/swagger-ui.html,就可以给前端展示相关的API文档，并像使用Postman以及Curl命令一样，通过Web界面进行接口测试。

结果

用yaml文件配置Swagger

先介绍两个docker镜像swaggerapi/swagger-editor和swaggerapi/swagger-ui

swaggerapi/swagger-editor

有两个重要的功能
1，提供编辑和预览接口示图的功能
2，提供导出和生成服务端和客户端代码功能

swaggerapi/swagger-ui

提供预览接口的作用
用-e指定配置文件的地址

关于yaml的格式规范

格式规范详情： https://swagger.io/specification/
但根据swaggerapi/swagger-editor 上示例代码问题。
也可以依葫芦画瓢。
但要有几点经验分享

  • response为必须
  • security 可有有无
  • 参数要加type
  • type为formData的要加前面要加consumes字段，内容可以”application/x-www-form-urlencoded”和multipart/form-data
  • in类型可以有header, formData, query, path
  • schema 的引用默认值不起作用
  • sheama 下的example，ref 不能跨域
  • Models 中要标表非必须的字段要required: false，会报错，说要是数组？
  • 修改后，models预览会有延迟
  • 默认值在type为string下不生校

生成代码

上面可选的语言有很多，包含广泛。
java的是用spring-boot为基础生成的。

关于try it out的execute

security部分是不包含在执行中的。
这里有点疑惑。

json 与yaml转化

使用npm的插件
https://www.npmjs.com/package/json2yaml

1
npm install -g json2yaml
1
json2yaml ./example.json > ./example.yml

感受

一开始示例配置很多，很多提示，给人很复杂的感觉。
后来试着自己写一遍，大概花大半天的时间试按上面的来摸索。
编辑器有很多提示，但提示与规范里有点不一样。
定义规范有些难理解，规范中的示例在编辑器中都跑不通。

愿景

  • modle没有写注释的地方，哪里可以加上就好
  • 这些接口再自动加上测试用例模板就更完美

时效

目前swagger的规范版本为：Version 3.0.0
swagger-editor版本为：2.0
swagger-ui版本为：2.0

参考

Swagger的简单介绍
https://blog.fengcl.com/2017/09/18/introduction-of-swagger/
作者
frank
发布于
2017年9月18日
许可协议