随着前后端分离的态势越演越烈,API文档是后端和前端交互(撕逼)的神器,古人通常在“纸上”写就一篇篇的API八股。随着自动化时代的来临,有了Swagger这样自动生成API文档的工具存在,后端的开发哥哥就再也不用挥汗如雨地书写API文档了。
关于Swagger的介绍网上已经数不胜数了,所以再班门弄斧的介绍就有点无聊了,所以这里还是直接介绍一下快速实践的流程,至于更高级的玩法,就交给列为看官自行研究了。
通过网址查看API
这里要假设你已经建好了Spring Boot工程,如果没有建好,可以去网上找找办法
那么,首先就是要在pom中引入相关的依赖了:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${spring.swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${spring.swagger.version}</version>
</dependency>
有了依赖之后,我会在config目录下,建立一个SwaggerConfig
类:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select() // 选择那些路径和API会生成document
.apis(RequestHandlerSelectors.basePackage("com.xxxxx.controller"))
.paths(PathSelectors.any()) // 对所有路径进行监控
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Service Title")
.description("相关wiki: ")
.contact(new Contact("Copperfield", "wiki_url", "xwhfcenter@gmail.com"))
.version("v1")
.build();
}
}
**记住打上两个注解: **@Configuration
和@EnableSwagger2
接下来, 就可以在com.xxxxx.controller
目录中创建相关的Controller类了,这里以常见的UserController为例
,对User的CRUD进行API描述:
@Api(description = "User相关的API说明") // 这个是Swagger的注解
@RestController
@RequestMapping(value = Constants.PATH_WITH_VERSION)
@Slf4j
public class UserController {
@ApiOperation(value = "新增用户(User)")
@RequestMapping(value = "/users/", method = RequestMethod.POST)
public GenericResp addUser(@RequestBody User user) {
...
}
@ApiOperation(value = "查找用户(User)")
@RequestMapping(value = "/users/{id}", method = RequestMethod.GET)
public GenericResp getUser(@PathVariable Integer id) {
...
}
@ApiOperation(value = "更新用户(User)")
@RequestMapping(value = "/users/{id}", method = RequestMethod.PATCH)
public GenericResp updateUser(@PathVariable String id, @RequestBody User user) {
...
}
@ApiOperation(value = "删除用户(User)")
@RequestMapping(value = "/users/{id}", method = RequestMethod.DELETE)
public GenericResp deleteUser(@PathVariable Integer id) {
...
}
}
对于User这个业务对象,可以这么定义User.class
:
public class User {
@ApiModelProperty(value = "User Id", hidden = true) // 这个是Swagger的注解
private Integer id;
@ApiModelProperty(value = "User Name")
private String userName;
@ApiModelProperty(value = "Nickname")
private String nickname;
@ApiModelProperty(value = "Password")
private String password;
@ApiModelProperty(value = "Phone")
private String phone;
@ApiModelProperty(value = "Email")
private String email;
}
这之后,run一下SpringApplication,就可以在浏览器输入网址http://localhost:8080/swagger-ui.html
查看API了:
[外链图片转存失败(img-YxzNeOwz-1564555390030)(https://raw.githubusercontent.com/xwhfcenter/picture_bed/master/Swagger_API.jpg)]
- 如果Service层和Dao层的代码写好了,可以在页面上进行API测试
- 习惯使用Postman的开发,可以在Postman中通过
Import From Link
把API文档导入到Postman中
通过文件查看(试验)
因为通过网址的方式,需要部署服务,初期来说不如文档传阅起来方便
pom文件中新增依赖
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
这里我新增了一个测试类SwaggerStaticDocTest
,以输出所有API到一个Markdown文件为例:
@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerStaticDocTest {
/* 输出Markdown到单文件 */
@Test
public void generateMarkdownDocsToFile() throws Exception {
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("src/docs/markdown/generated/all"));
}
}
运行测试,路径src/docs/markdown/generated
下生成文件all.md
Markdow看起来没有网址看的舒服,而且不能用来测试,所以有条件了话研究一下有没有途径专门部署Swagger API来得更有效率,官方的付费工具SwaggerHub,肯定是最好用的吧?