如何用Swagger生成API文档

随着前后端分离的态势越演越烈，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，肯定是最好用的吧?