Spring MVC中使用Swagger生成API文档和完整项目示例Demo，swagger-server-api

骑猪看日落 2022-05-24 11:41 201阅读 0赞

原文地址：https://blog.csdn.net/fansunion/article/details/51923720

实际项目中非常需要写文档，提高Java服务端和Web前端以及移动端的对接效率。  
  听说Swagger这个工具，还不错，就网上找了些资料，自己实践了下。

一：Swagger介绍

Swagger是当前最好用的Restful API文档生成的开源项目，通过swagger-spring项目

实现了与SpingMVC框架的无缝集成功能，方便生成spring restful风格的接口文档，

同时swagger-ui还可以测试spring restful风格的接口功能。

官方网站为：http://swagger.io/

中文网站：http://www.sosoapi.com

二：Swagger与Spring MVC集成步骤

1.Maven关键配置

<dependency>
                <groupId>com.mangofactory</groupId>
                <artifactId>swagger-springmvc</artifactId>
                <version>1.0.2</version>
            </dependency>
     
     <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
            <version>4.1.6.RELEASE</version>
          </dependency>

2. 插件配置  
   CustomJavaPluginConfig

3.复制swagger的相关js等静态资源到webapp目录。  
   swagger-ui.js之类的。  
   我copy过一次，但是有问题，最后从网上下载了一个项目，可以直接用的那种。  
   然后自己再逐步改造。

4.启动项目  
   http://localhost:8080/

![Center][]

三、常见swagger注解一览与使用  
最常用的5个注解  
@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

其它若干

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiClass

@ApiError

@ApiErrors

@ApiParamImplicit

@ApiParamsImplicit

@ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
        @ResponseBody
        @RequestMapping(value = "list", method = RequestMethod.POST)
        public Result<User> list(
                @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
                @ApiParam(value = "token", required = true) @RequestParam String token) {
            Result<User> result = new Result<User>();
            User user = new User();
            result.setData(user);
            return result;
        }

四、关键代码和实际例子  
    例子1：  
     
  
   @ApiParam(value = "token", required = true) @RequestParam String token  
Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。

例子2：

@ApiOperation(value = "update用户", notes = ")", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
        @ResponseBody
        @RequestMapping(value = "update", method = RequestMethod.GET/*,produces = MediaType.APPLICATION_FORM_URLENCODED_VALUE*/)
        public Result<String> update(User user) {
            String u = findUser(user);
            System.out.println(u);
            return null;
        }

当参数太多的时候，需要定义太多的参数，排版看起来很不舒服。  
这个时候，可以使用对象来接收。

@ApiModel(value = "用户对象",description="user2") 
    public class User extends CommonParam{
    
    }

Web前端/移动端HTTP请求方式：直接把参数附带到URL后面，或者用AJAX方法，表单提交。  
这里面存在一个小问题，当后端用对象User来接收参数的时候，Swagger自带的工具是这样的：  
 ![Center 1][]  
这种形式，并不是表单提交，或者把参数附加到URL的后面。  
我们只能手动构造URL，附带参数去提交。  
如果需要测试的话！

例子3：

public Result<String> add(@RequestBody User user) {
            String u = findUser(user);
            System.out.println(u);
            return null;
        }

Web前端/移动端HTTP请求方式：必须把参数，放到request请求的body中去。  
后端不能直接用request.getParam("token")这种。获得request body中的数据，手动转换成目标数据。

String charReader(HttpServletRequest request) throws IOException {
    
            BufferedReader br = request.getReader();
    
            String str, wholeStr = "";
            while ((str = br.readLine()) != null) {
                wholeStr += str;
            }
            return wholeStr;
    
        }

个人推荐：  
1.参数不多的时候，用例子1，用@ApiParam注解生成文档。  
  swagger可视化界面，可以直接设置参数，发送请求来测试  
2.参数比较多的时候，用例子2，用对象来接收参数，在对象里针对每个字段，@ApiModelProperty注解生成文档。  
   swagger可视化界面，可以直接设置参数，但是无法接收到。  
  因此，推荐使用其它HTTP请求或POST模拟工具，发送请求，模拟测试。

不推荐例子3，不通用，局限性比较大。

五、若干截图  
![Center 2][]

![Center 3][]

![Center 4][]

六、源代码

package cn.fansunion.swagger.serverapi.controller;
     
    import org.springframework.http.MediaType;
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.ResponseBody;
     
    import com.wordnik.swagger.annotations.Api;
    import com.wordnik.swagger.annotations.ApiOperation;
    import com.wordnik.swagger.annotations.ApiParam;
     
    /**
     * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
     * 博客：http://blog.csdn.net/fansunion
     *
     */
    @Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)
    @Controller
    @RequestMapping("user")
    public class UserController {
     
        // 列出某个类目的所有规格
        @ApiOperation(value = "获得用户列表", notes = "列表信息", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
        @ResponseBody
        @RequestMapping(value = "list", method = RequestMethod.POST)
        public Result<User> list(
                @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId,
                @ApiParam(value = "分类ID", required = true) @RequestParam Long categoryId2,
                @ApiParam(value = "token", required = true) @RequestParam String token) {
            Result<User> result = new Result<User>();
            User user = new User();
            result.setData(user);
            return result;
        }
     
        @ApiOperation(value = "添加用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
        @ResponseBody
        @RequestMapping(value = "add", method = RequestMethod.POST)
        // @RequestBody只能有1个
        // 使用了@RequestBody，不能在拦截器中，获得流中的数据，再json转换，拦截器中，也不清楚数据的类型，无法转换成java对象
        // 只能手动调用方法
        public Result<String> add(@RequestBody User user) {
            String u = findUser(user);
            System.out.println(u);
            return null;
        }
     
        @ApiOperation(value = "update用户", notes = "获取商品信息(用于数据同步)", httpMethod = "POST", produces = MediaType.APPLICATION_JSON_VALUE)
        @ResponseBody
        @RequestMapping(value = "update", method = RequestMethod.GET)
        public Result<String> update(User user) {
            String u = findUser(user);
            System.out.println(u);
            return null;
        }
     
        private String findUser(User user) {
            String token = user.getToken();
            return token;
        }
    }

package cn.fansunion.swagger.serverapi.controller;
     
    import com.wordnik.swagger.annotations.ApiModel;
    import com.wordnik.swagger.annotations.ApiModelProperty;
     
    /**
     * 小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119
     * 博客：http://blog.csdn.net/fansunion
     *
     */
    @ApiModel(value = "用户对象", description = "user2")
    public class User extends CommonParam {
     
        @ApiModelProperty(value = "商品信息", required = true)
        private String name;
        @ApiModelProperty(value = "密码", required = true)
        private String password;
     
        @ApiModelProperty(value = "性别")
        private Integer sex;
        @ApiModelProperty(value = "密码", required = true)
        private String token;
     
        public String getToken() {
            return token;
        }
     
        public void setToken(String token) {
            this.token = token;
        }
     
        public String getName() {
            return name;
        }
     
        public void setName(String name) {
            this.name = name;
        }
     
        public String getPassword() {
            return password;
        }
     
        public void setPassword(String password) {
            this.password = password;
        }
     
        public Integer getSex() {
            return sex;
        }
     
        public void setSex(Integer sex) {
            this.sex = sex;
        }
     
    }

package cn.fansunion.swagger.serverapi.swagger;
     
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.DefaultServletHandlerConfigurer;
    import org.springframework.web.servlet.config.annotation.EnableWebMvc;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
     
    import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
    import com.mangofactory.swagger.models.dto.ApiInfo;
    import com.mangofactory.swagger.paths.SwaggerPathProvider;
    import com.mangofactory.swagger.plugin.EnableSwagger;
    import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
     
    @Configuration
    @EnableWebMvc
    @EnableSwagger
    public class CustomJavaPluginConfig extends WebMvcConfigurerAdapter {
     
        private SpringSwaggerConfig springSwaggerConfig;
     
        @Autowired
        public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
            this.springSwaggerConfig = springSwaggerConfig;
        }
     
        /**
         * 链式编程 来定制API样式 后续会加上分组信息
         * 
         * @return
         */
        @Bean
        public SwaggerSpringMvcPlugin customImplementation() {
            return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                    .apiInfo(apiInfo()).includePatterns(".*")
                    .useDefaultResponseMessages(false)
                //    .pathProvider(new GtPaths())
                    .apiVersion("0.1").swaggerGroup("user");
     
        }
     
        private ApiInfo apiInfo() {
            ApiInfo apiInfo = new ApiInfo("小雷移动端API接口平台",
                    "提供详细的后台所有Restful接口", "http://blog.csdn.net/FansUnion",
                    "FansUnion@qq.com", "小雷博客", "http://blog.csdn.net/FansUnion");
            return apiInfo;
        }
     
        @Override
        public void configureDefaultServletHandling(
                DefaultServletHandlerConfigurer configurer) {
            configurer.enable();
        }
     
        class GtPaths extends SwaggerPathProvider {
     
            @Override
            protected String applicationPath() {
                return "/restapi";
            }
     
            @Override
            protected String getDocumentationPath() {
                return "/restapi";
            }
        }
     
    }

七、项目下载地址  
  http://git.oschina.net/fansunion/swagger-server-api/tree/master/

八、参考资料  
http://blog.csdn.net/jia20003/article/details/50700736  
http://www.cnblogs.com/quanyongan/archive/2013/04/16/3024741.html  
http://www.cnblogs.com/h9527/p/5506956.html  
http://www.cnblogs.com/yuananyun/p/4993426.html

**       微信公众号： **

![20180403143416927][]

JAVA程序猿成长之路

分享资源，记录程序猿成长点滴。专注于Java,Spring,SpringBoot,SpringCloud，分布式，微服务。

[Center]: /images/20220524/494ef93c5ea140b4a38ea2bcd9558719.png
[Center 1]: /images/20220524/70862560b8d4431898c66e9a781f5d23.png
[Center 2]: /images/20220524/439aa4774e0448b6bd0ba3a9c95c122b.png
[Center 3]: /images/20220524/91d016cde11a453eb316785831f7e591.png
[Center 4]: /images/20220524/d9bf389f60474dc4b4cacf7402113eb8.png
[20180403143416927]: /images/20220524/20e3d4dc9a6c499f8064b6729f294c6c.png