swagger + springmvc配置使用文档

朱雀 2022-05-11 12:34 443阅读 0赞

# 1. Swagger概述 #

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

** 作用：**

1. 接口的文档在线自动生成，方便管理项目中API接口。

2. 方便前后端联合开发，以及三方调用。

3. 方便接口测试。

以下是我们项目中swagger+springmvc的配置使用步骤，文中示例代码仅供使用参考，不能直接运行。

# 2. swagger + springmvc配置使用步骤 #

**一、在****pom.xml****中引入****maven****依赖。**

<dependency> 
   <groupId>io.springfox</groupId> 
   <artifactId>springfox-swagger2</artifactId> 
   <version>2.4.0</version> 
</dependency> 
<dependency> 
   <groupId>io.springfox</groupId> 
   <artifactId>springfox-swagger-ui</artifactId> 
   <version>2.4.0</version> 
</dependency> 
<dependency> 
   <groupId>org.webjars</groupId> 
   <artifactId>bootstrap</artifactId> 
   <version>3.3.6</version> 
</dependency>

**二、添加自定义****SwaggerConfig.java****类文件，文件内容如下：** 
 
/\*\* 
 \* Created by davidpeng on 16/5/13. 
 \*/ 
@Configuration 
@EnableSwagger2 
@EnableWebMvc 
public class SwaggerConfig \{ 
 
    @Bean 
    public Docket userAPI() \{ 
 
        ApiInfo apiInfo = new ApiInfo( 
                "接口文档", 
                "XX项目的接口文档，此文档包含user级别的所有接口说明。", 
                "", 
                "", 
                new Contact("davidpeng", "", "[1551XXXX@qq.com][1551XXXX_qq.com]"), 
                "", 
                "" 
        ); 
 
        Set<String> setProtocol = new HashSet<String>(); 
        setProtocol.add("http"); 
 
        Set<String> setProduce = new HashSet<String>(); 
        setProduce.add("application/json"); 
 
        Set<String> setConsume = new HashSet<String>(); 
        setConsume.add("x-www-form-urlencoded"); 
 
        List<Parameter> listParameter = new ArrayList<Parameter>(); 
 
        listParameter.add( 
                new ParameterBuilder() 
                        .name("X-Toon-User-ID") 
                        .description("User ID") 
                        .parameterType("header") 
                        .required(true) 
                        .modelRef(new ModelRef("string")) 
                        .build() 
        ); 
 
        listParameter.add( 
                new ParameterBuilder() 
                        .name("X-Toon-User-Token") 
                        .description("User Token") 
                        .parameterType("header") 
                        .required(true) 
                        .modelRef(new ModelRef("string")) 
                        .build() 
        ); 
 
        listParameter.add( 
                new ParameterBuilder() 
                        .name("X-Toon-User-Agent") 
                        .description("User Agent") 
                        .parameterType("header") 
                        .required(true) 
                        .modelRef(new ModelRef("string")) 
                        .build() 
        ); 
 
        return new Docket(DocumentationType.SWAGGER\_2) 
                .select() 
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 
                    .paths(PathSelectors.regex("/user/.\*")) 
                    .build() 
                .groupName("User") 
                .pathMapping("/") 
                .enable(true) 
                .apiInfo(apiInfo) 
                .useDefaultResponseMessages(false) 
                .globalOperationParameters(listParameter) 
                .protocols(setProtocol) 
                .produces(setProduce) 
                .consumes(setConsume); 
    \} 
 
    @Bean 
    public Docket openAPI() \{ 
 
        ApiInfo apiInfo = new ApiInfo( 
                "接口文档", 
                "XX项目的接口文档，此文档包括open级别的所有接口说明", 
                "", 
                "", 
                new Contact("davidpeng", "", "[1551XXXX@qq.com][1551XXXX_qq.com]"), 
                "", 
                "" 
        ); 
 
        Set<String> setProtocol = new HashSet<String>(); 
        setProtocol.add("http"); 
 
        Set<String> setProduce = new HashSet<String>(); 
        setProduce.add("application/json"); 
 
        Set<String> setConsume = new HashSet<String>(); 
        setConsume.add("x-www-form-urlencoded"); 
 
        List<Parameter> listParameter = new ArrayList<Parameter>(); 
 
        return new Docket(DocumentationType.SWAGGER\_2) 
                .select() 
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 
                    .paths(PathSelectors.regex("/open/.\*")) 
                    .build() 
                .groupName("Open") 
                .pathMapping("/open") 
                .enable(true) 
                .apiInfo(apiInfo) 
                .useDefaultResponseMessages(false) 
                .globalOperationParameters(listParameter) 
                .protocols(setProtocol) 
                .produces(setProduce) 
                .consumes(setConsume); 
    \} 
 
    @Bean 
    public UiConfiguration uiConfig() \{ 
        return new UiConfiguration( 
                "validatorUrl",// url 
                "none",       // docExpansion          => none | list 
                "alpha",      // apiSorter             => alpha 
                "schema",     // defaultModelRendering => schema 
                true,         // enableJsonEditor      => true | false 
                true);        // showRequestHeaders    => true | false 
    \} 
 
\}

注：其中ApiInfo构造参数需要做相应修改，其它参数可以使用文件中配置好的，各参数和注解含义在此不做说明，如需了解请自己查看官方文档。

**三、将上一步中****SwaggerConfig****配置加入****Spring****容器中（****dispatcher-servlet.xml****），如下：**

<bean class="com.XXXX.api.swagger.SwaggerConfig" />

**四、为了访问****swagger-ui.html****等静态资源，需在****dispatcher-servlet.xml****中加入如下配置：**

<mvc:resources mapping="/\*\*" location="/"/>

**五、由于当前****API****项目中包含不同级别的****API****接口，所以配置不同的拦截器用以处理不同级别接口相关验证，在****dispatcher-servlet.xml****中加入如下配置：**

<mvc:interceptors> 
   <mvc:interceptor> 
      <mvc:mapping path="/user/\*"/> 
      <bean id="baseRequestInterceptor" class="com.XXX.commons.api.user.XXXRequestInterceptor"> 
         <property name="ignoreVerifyList"> 
            <list> 
               <value>addRecommendation</value> 
               <value>checkRecommendStatus</value> 
               <value>createCustomField</value> 
               <value>deleteCustomField</value> 
               <value>getListConfigField</value> 
               <value>getListCofigFieldValue</value> 
               <value>getListCustomField</value> 
               <value>.....</value> 
            </list> 
         </property> 
      </bean> 
   </mvc:interceptor> 
   <mvc:interceptor> 
      <mvc:mapping path="/open/\*"/> 
      <bean class="com.XXX.commons.api.open.XXXRequestInterceptor" /> 
   </mvc:interceptor> 
</mvc:interceptors>

**六、在****Controller****中添加****Swagger****相关注解，配置如下：**

1、在Controller类上的注解如下：

@Api(value = "user", tags = "User Category", description = "User endpoint")

注：此注解可以写到所有Controller继承的BaseController上，否则需要在每个Controller上都加上此注解。

2、方法注解GET请求范例：

@Resource(name = "userServiceImpl") 
    private IUserService2ApiService userService2Api; 
 
    @RequestMapping(value = "getListRelationItem", 
            method = RequestMethod.GET, 
            produces = "application/json") 
//            consumes = "application/x-www-form-urlencoded") 
    @ApiOperation( 
            value = "获取用户XX关系列表接口", 
            notes = "返回用户对应的Id和使用状态." \+ 
                    "Method: GET" \+ 
                    "Error Code: " \+ 
                    "<font color=\\"red\\">3000: 参数错误" \+ 
                    "<font color=\\"red\\">3004: 服务异常" \+ 
                    "<font color=\\"red\\">3005: 操作失败", 
            response = RelationItemList.class 
    ) 
    public void getListRelationItem(@ModelAttribute GetListRelationItemInput input) \{ 
        //处理参数 
        if(Utils.isNull(input))\{ 
            input = new GetListRelationItemInput(); 
        \} 
 
        //设置用户id 
        input.setUserId(super.parseRequestHeaderInfo().getUserId()); 
 
        //验证参数 
        if(!this.verifyParam(input))\{ 
            super.outputException(ExceptionConstants.PARAMETER\_ERROR.getCode(), 
                    ExceptionConstants.PARAMETER\_ERROR.getMsg()); 
            return; 
        \} 
        //调用业务方法 
        CommonBusinessOutput output = null; 
        try \{ 
            output = this.userService2Api.getListRelationItem( 
                    new CommonBusinessInput<>(input)); 
        \} catch (Exception e) \{ 
            super.LOGGER.error("GetListRelationItemController-getListRelationItem:", e); 
            super.outputException(ExceptionConstants.SERVER\_EXCEPTION.getCode(), 
                    ExceptionConstants.SERVER\_EXCEPTION.getMsg()); 
            return; 
        \} 
        //处理服务异常 
        if(null == output)\{ 
            super.outputException(ExceptionConstants.SERVER\_EXCEPTION.getCode(), 
                    ExceptionConstants.SERVER\_EXCEPTION.getMsg()); 
            return; 
        \} 
        //处理业务异常 
        if(!output.isReturnStatus())\{ 
            ExceptionConstants e = this.handleBizException(output); 
            super.outputException(e.getCode(), e.getMsg()); 
            return; 
        \} 
        if(null == output.getData())\{ 
            super.outputData(); 
            return; 
        \} 
        super.outputData(output.getData()); 
    \}

3、方法注解POST请求范例：

@RequestMapping(value = "updateUser", 
        method = RequestMethod.POST, 
        produces = "application/json", 
        consumes = "application/json") 
@ApiOperation( 
        value = "更新用户信息接口", 
        notes = "此接口可更新主表信息、位置表信息、主表扩展信息." \+ 
                "Method: POST" \+ 
                "Error Code: " \+ 
                "<font color=\\"red\\">3000: 参数错误" \+ 
                "<font color=\\"red\\">3004: 服务异常" \+ 
                "<font color=\\"red\\">3005: 操作失败", 
        response = UserS2Api.class 
) 
public void updateUser(@RequestBody UpdateUserInput input) \{ 
    //处理参数 
    if(Utils.isNull(input))\{ 
        input = new UpdateUserInput(); 
    \} 
 
    //设置用户id 
    input.setOwnByUserId(super.parseRequestHeaderInfo().getUserId()); 
 
    //验证参数 
    if(!this.verifyParam(input))\{ 
        super.outputException(ExceptionConstants.PARAMETER\_ERROR.getCode(), 
                ExceptionConstants.PARAMETER\_ERROR.getMsg()); 
        return; 
    \} 
    //调用业务方法 
    CommonBusinessOutput output = null; 
    try \{ 
        output = this.userService2Api.updateUser( 
                new CommonBusinessInput<>(input)); 
    \} catch (Exception e) \{ 
        super.LOGGER.error("UpdateCardController-updateCard:", e); 
        super.outputException(ExceptionConstants.SERVER\_EXCEPTION.getCode(), 
                ExceptionConstants.SERVER\_EXCEPTION.getMsg()); 
        return; 
    \} 
    //处理服务异常 
    if(null == output)\{ 
        super.outputException(ExceptionConstants.SERVER\_EXCEPTION.getCode(), 
                ExceptionConstants.SERVER\_EXCEPTION.getMsg()); 
        return; 
    \} 
    //处理业务异常 
    if(!output.isReturnStatus())\{ 
        ExceptionConstants e = this.handleBizException(output); 
        super.outputException(e.getCode(), e.getMsg()); 
        return; 
    \} 
    if(null == output.getData())\{ 
        super.outputData(); 
        return; 
    \} 
    super.outputData(output.getData()); 
\}

注：1、方法参数必须以自定义对象接收，GET请求使用@ModelAttribute注解，POST请求使用@RequestBody 注解；

2、方法返回值只能是以下情况：无返回值、返回对象、返回List<对象>。若方法无返回值，则@ApiOperation注解中response参数值为Void.class；若方法返回值为对象，则response参数值为对象名.class；若方法返回值为List<对象>，则response参数值为对象名.class，并新增参数responseContainer，值为"List"，example：response = 对象名.class,responseContainer="List"。

**七、部署项目，访问以下地址：**

[http://host:port/swagger-ui.html][http_host_port_swagger-ui.html]

![70][]

--------------------

如果您觉得博主写的文章对您有帮助，可以请博主喝杯茶哦，O(∩\_∩)O~

![70 1][]

博主：[诸葛本不亮][Link 1]

简介：毕业后做过多年程序猿、架构设计、项目经理、部门总监，待过传统软件公司，也在大型互联网公司负责过平台研发部，在这个行业浸淫十多年，在系统架构、SaaS平台搭建、项目管理以及部门管理等方面有着多年的一线实践经验。

目前与好友合伙创办了一个软件工作室，提供各类系统解决方案、咨询服务及技术合作，企业软件（SaaS平台、企业应用、商城、微信公众号及小程序开发）定制开发服务，大数据服务（数据采集及清洗、数据分析等），以及程序猿职业规划及转型咨询服务（程序猿转架构师、转项目管理、转技术管理等，可以提供相应的一线资料帮助您成功转型，获得大厂offer）。

微信号：danwang2138

![70 2][]

[1551XXXX_qq.com]: mailto:zhaoteng1@syswin.com
[mvc_default-servlet-handler]: http://mvcdefault-servlet-handler/
[http_host_port_swagger-ui.html]: http://172.28.17.28:8081/swagger-ui.html
[70]: /images/20220505/c109e2f1c5fe48d594dd50b63986bfa1.png
[70 1]: /images/20220505/92c3bf20a46d4699bdaafa76e2316690.png
[Link 1]: https://blog.csdn.net/david_pfw
[70 2]: /images/20220505/6a27f779c6bf4c7f844e2ad619f61368.png