基于 Swagger 快速构建 Rest OpenAPI 文档

/ JavaWeb / 775浏览

Swagger是一个简单易用的工具,不仅为我们的API调用生成文档,还提供了一个可以援引这些文档的易用的web客户端。
在SpringMvc中,可以通过Swagger文档工具来生产开放的API文档,供公开使用。

加入Maven依赖

首先在pom文件中指定Swagger:

<dependency>
	<groupId>com.mangofactory</groupId>
	<artifactId>swagger-springmvc</artifactId>
	<version>1.0.2</version>
</dependency>

配置Swagger

接下来,需要告诉Swagger想要为哪些控制器类生成文档。我们需要引入一个称为SwaggerConfig的新类,它包含Swagger的各种配置。

package cn.zealon.config;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
import com.mangofactory.swagger.models.dto.ApiInfo;
import com.mangofactory.swagger.plugin.EnableSwagger;
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

/**
 * Swagger全局配置
 * @auther: Zealon
 * @Date: 2017-10-14 16:13
 */
@Configuration
@EnableSwagger
public class SwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }
    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
            "API 示例",
            "My Apps API Description",
            "My Apps API terms of service",
            "zealon@126.com",
            "My Apps API Licence Type",
            "My Apps API License URL"
        );
        return apiInfo;
    }
}

引入Swagger UI静态文件

静态文件,可以到Github中去下载最新版本。
下载地址:swagger-ui
下载后,把dist文件夹,拷贝到spring工程的静态资源文件中即可。

然后进入dist/index.html修改数据源url地址: https://petstore.swagger.io/v2/swagger.json修改为,
http://localhost:8080/api-docs,也就是你项目的地址。

Controller配置Swagger注解

最后,在需要增加API说明的控制器类中,增加Swagger的注解来进行描述。

@Api,整个类说明 @ApiOperation,类中的方法说明

package cn.zealon.controller;

import cn.zealon.entity.User;
import com.wordnik.swagger.annotations.Api;
import com.wordnik.swagger.annotations.ApiOperation;
import com.wordnik.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

/**
 * @auther: Zealon
 * @Date: 2017-10-14 16:31
 */

@RestController
@RequestMapping("sample")
@Api(value="sample")
public class SampleController {

    @GetMapping("/getUserById")
    @ApiOperation(value = "通过ID查询User信息", httpMethod = "GET", notes = "暂无")
    public String getUserById(@ApiParam(required = true, name = "id", value = "用户ID") String id) {
        return "id:"+id;
    }

    @PostMapping("saveUser")
    @ApiOperation(value = "保存用户信息", httpMethod = "POST",response = User.class, notes = "暂无")
    public String saveUser(@ApiParam(required = true, name = "paramData", value = "用户信息") @RequestBody User paramData) {

        return paramData.toString();
    }
}

测试

启动工程,访问swagger静态资源下的index.html。
如图: alt 点击任意一个方法,可以看到请求类型、说明、参数等等,点击Try,便可进行测试了。 alt

你还可以用Swagger做许多事情,更多详情可以去查看它的官方文档(https://swagger.io)。