使用swagger为Spring REST API生成在线文档

本文介绍如何使用swaggerUI为Spring Boot项目创建动态的、从代码生成的REST API文档

创建SwaggerUI渲染需要的JSON

• 首先为项目添加生成JSON的库：

dependencies {
    compile "io.springfox:springfox-swagger2:2.7.0"
}

• 添加SwaggerConfig类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket generateDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .paths(paths()) // and by paths
                .build()
                .apiInfo(apiInfo());
    }


    //Here is an example where we select any api that matches one of these paths
    private Predicate<String> paths() {
        return input -> input.matches(".api.*");
    }


    private ApiInfo apiInfo() {
        return new ApiInfo("王郁的API文档",
                "提供App测试及独立APP研发",
                "2.0",
                "http://wycode.cn",
                new Contact("王郁","wycode.cn","wangyu0503@gmail.com"),
                "wycode.cn All Right Reserved",
                "http://wycode.cn",
                new ArrayList<>());
    }
}

• 访问http://localhost:8080/v2/api-docs可以看到JSON即说明配置成功：

{
    "swagger": "2.0",
    "info": {
        "description": "提供App测试及独立APP研发",
        "version": "2.0",
        "title": "王郁的API文档",
        "termsOfService": "http://wycode.cn",
        "contact": {},
        "license": {}
    },
    "host": "localhost:8080",
    "basePath": "/",
    "tags": [],
    "paths": {
        "/api/hello": {
            "get": {},
            "head": {},
            "post": {},
            "put": {},
            "delete": {},
            "options": {},
            "patch": {}
        }
    },
    "definitions": {}
}

• 添加SwaggerUI包

从SwaggerUI的github上下载最新版，将里面的dist文件夹，放入我们工程的静态页面目录

因为我们要修改index.html，所以不能使用webjars

对index.html的常量ui做如下更改

// Build a system
  const ui = SwaggerUIBundle({
    url: "/v2/api-docs", //API的JSON地址
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

大功告成！

添加文档注释

• 实体注解

@ApiModel(value = "Hello 消息",description = "Hello接口返回的消息实体")
public class Hello {

    @ApiModelProperty("消息")
    private String message;

    ...
}

• 接口注解

@Api(value = "Hello", description = "第一个api",tags = "Hello")
@RestController
public class HelloController {

    @ApiOperation(value = "Say Hello", produces = "application/json ")
    @RequestMapping("/api/hello")
    public Hello hello(@ApiParam(value = "消息",defaultValue = "Hello World!") @RequestParam(name = "message",defaultValue = "Hello World!")String message){
        return  new Hello("message is : "+ message);
    }
}

本文原始发表于: 王郁的小站 | 使用swagger为Spring REST API生成在线文档 (wycode.cn), 转载请注明出处