引入swagger(1)——与传统spring整合

柔光的暖阳◎ 2022-06-08 04:17 174阅读 0赞

Swagger是一个rest api文档解决方案。对于有手机端app的企业来说，维护一套api文档是一件麻烦的事情，app端和后端人员的沟通将浪费过多时间。如果人数不够，单元测试也是麻烦的事情。Swagger是一个很好的解决方案。

Swagger的整合准备分两篇文章简绍

1、与传统spring整合

2、与spring-boot整合

spring-boot相当方便，还是建议大家新的工程都用spring-boot

#         pom #

swagger2开始已经融合到springfox中了，因此依赖如下：

<dependency>
    		    <groupId>com.mangofactory</groupId>
    		    <artifactId>swagger-springmvc</artifactId>
    		    <version>1.0.2</version>
    		</dependency>
    		
    		<dependency>
    		    <groupId>com.fasterxml.jackson.core</groupId>
    		    <artifactId>jackson-databind</artifactId>
    		    <version>2.4.2</version>
    		</dependency>
    		
    		<dependency>
    		    <groupId>org.webjars.bower</groupId>
    		    <artifactId>swagger-ui</artifactId>
    		    <version>2.1.8-M1</version>
    		</dependency>
    		<dependency>
    		    <groupId>com.google.guava</groupId>
    		    <artifactId>guava</artifactId>
    		    <version>15.0</version>
    		</dependency>
    		 
            <dependency>
    		    <groupId>org.hibernate</groupId>
    		    <artifactId>hibernate-validator</artifactId>
    		</dependency>

注意这里的swagger-ui版本为2.1.8，下载swagger-ui的时候一定要下载配套的版本，不然会出现找不到api文档的提示

#         配置 #

既然现在都是用spring4，那就别用xml来配置了，这里提供java config

import javax.servlet.ServletContext;
    
    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.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.RelativeSwaggerPathProvider;
    import com.mangofactory.swagger.plugin.EnableSwagger;
    import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
    
    @Configuration
    @EnableWebMvc
    @EnableSwagger
    public class SpringfoxConfig extends WebMvcConfigurerAdapter {
    
    	public static String PROJECT_NAME;
        
        @Autowired
        private ServletContext servletContext;
    
        static {
            PROJECT_NAME = "xxx的api";
        }
    
        private SpringSwaggerConfig springSwaggerConfig;
    
        @Autowired
        public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
            this.springSwaggerConfig = springSwaggerConfig;
        }
    
        /**
         * 链式编程 来定制API样式
         * 后续会加上分组信息
         *
         * @return
         */
        @Bean
        public SwaggerSpringMvcPlugin customImplementation() {
        	
        	RelativeSwaggerPathProvider swaggerPathProvider = new RelativeSwaggerPathProvider(servletContext);
        	
        	swaggerPathProvider.setApiResourcePrefix("rest");
        	
            return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                    .apiInfo(apiInfo())
                    .includePatterns(".*")
                    .pathProvider(swaggerPathProvider)
                    .apiVersion("0.0.1");
        }
    
        private ApiInfo apiInfo() {
            ApiInfo apiInfo = new ApiInfo(
                    PROJECT_NAME + " API",
                    PROJECT_NAME + " xxxAPI文档",
                    "http://localhost/api-doc/index.html",
                    "guduyishuai@163.com",
                    "xxx",
                    "xxx"
            );
            return apiInfo;
        }
    	
    }

注意，通过RelativeSwaggerPathProvider来设置相对路径，比如你的rest接口路径都是以/rest开头，那么就需要通过该类进行设置。此外，还有一个绝对地址的设置类。

给一个比较全面的配置地址

http://grepcode.com/file/repo1.maven.org/maven2/com.mangofactory/swagger-springmvc/0.8.7/com/mangofactory/swagger/configuration/SpringSwaggerConfig.java\#SpringSwaggerConfig.0servletContext

#     #

# swagger-ui #

下载相应版本的swagger-ui，比如这里用swaggr-ui 2.1.5。如果版本不对，那么将找不到rest api

将dist文件夹放到web容器中。如果前后端没有分离，放到webroot或webapp下。如果使用nginx进行前后端分离，那么将dist放到相应的文件夹中，比如我创建一个

api-doc文件夹，并把dist文件中的内容放入其中。

修改index.html文件，将请求路径换成rest接口根路径+api-docs，比如：http://localhost/ecouponApi/rest/api-docs

# 加入header信息 #

大部分情况，手机端的身份验证需要通过http header来进行，为了使用header，需要在接口方法上加上如下注释

@ApiImplicitParams({
            @ApiImplicitParam(paramType="header", name = "xytkj-auth-token", value = "token", required = true, dataType = "String")
        })

最后说一下，同样可以使用@ModelAttribute和@PathVariable来进行参数指定

@ApiImplicitParam和@ApiParam

@ApiImplicitParam的query类型参数可以通过request获取，和@RequestParam为独立的参数。@ApiParam仅仅注解request上的参数

比如：以下配置是错误的

@ResponseBody
        @RequestMapping(value = "/loginout", method = RequestMethod.POST)
        @ApiOperation(value="退出登录", notes="退出登录")
        @ApiImplicitParams({
            @ApiImplicitParam(paramType="header", name = "xytkj-auth-token", value = "令牌", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "phone", value = "电话号码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType="query", name = "sign", value = "签名", required = true, dataType = "String")
        })
        public void loginout(
        		@RequestParam("phone") String phone,
                @RequestParam("sign") String sign,  
                HttpServletRequest request,
                HttpServletResponse response) throws SysException {
    
    }

正确写法如下

@ResponseBody
        @RequestMapping(value = "/loginout", method = RequestMethod.POST)
        @ApiOperation(value="退出登录", notes="退出登录")
        @ApiImplicitParams({
            @ApiImplicitParam(paramType="header", name = "xytkj-auth-token", value = "令牌", required = true, dataType = "String")
        })
        public void loginout(
        		@ApiParam(required=true,value="电话",name="phone")
        		@RequestParam("phone") String phone,
        		@ApiParam(required=true,value="签名",name="sign")
                @RequestParam("sign") String sign,  
                HttpServletRequest request,
                HttpServletResponse response) throws SysException {
    
    }

访问api文档

地址为：swagger-ui的index.html

# 最后看下效果 #

![Center][]

![Center 1][]

![Center 2][]

[Center]: /images/20220608/9c33ebc948e84dc286ca09da10bf4358.png
[Center 1]: /images/20220608/966934a541e9499891c0067340003df8.png
[Center 2]: /images/20220608/d5a74a79a95d4876a5a2b1bcdf9e1b62.png