SwaggerSpringMvc

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。
如图： 点击任意一个方法，可以看到请求类型、说明、参数等等，点击Try，便可进行测试了。

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

作者： Zealon
崇尚简单，一切简单自然的事物都是美好的。