使用swagger作为restful api的doc文档生成

初衷

记得以前写接口，写完后会整理一份API接口文档，而文档的格式如果没有具体要求的话，最终展示的文档则完全决定于开发者的心情。也许多点，也许少点。甚至，接口总是需要适应新需求的，修改了，增加了，这份文档维护起来就很困难了。于是发现了swagger，自动生成文档的工具。

swagger介绍

首先，官网这样写的：

Swagger – The World's Most Popular Framework for APIs.

因为自强所以自信。swagger官方更新很给力，各种版本的更新都有。swagger会扫描配置的API文档格式自动生成一份json数据，而swagger官方也提供了ui来做通常的展示，当然也支持自定义ui的。不过对后端开发者来说，能用就可以了，官方就可以了。

最强的是，不仅展示API，而且可以调用访问，只要输入参数既可以try it out.

效果为先，最终展示doc界面，也可以设置为中文：

在spring-boot中使用

以前总是看各种博客来配置，这次也不例外。百度了千篇一律却又各有细微的差别，甚至时间上、版本上各有不同。最终还是去看官方文档，终于发现了官方的sample。针对于各种option的操作完全在demo中了，所以clone照抄就可以用了。

github sample源码

配置

1.需要依赖两个包：

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${springfox-version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${springfox-version}</version>
        </dependency>

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

2.swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.test.web.controllers";
    public static final String VERSION = "1.0.0";

    ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger API")
                .description("This is to show api description")
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .termsOfServiceUrl("")
                .version(VERSION)
                .contact(new Contact("","", "miaorf@outlook.com"))