java效率开发之使用swagger, 同时推荐使用加强swagger-UI

前言

现代化的研发组织架构中，一个研发团队基本包括了 产品组、后端组、前端组、APP端研发、 测试组、 UI组等，各个细分组织人员各司其职，共同完成产品的全周期工做。如何进行组织架构内的有效高效沟通就显得尤为重要。其中，如何构建一份合理高效的接口文档更显重要。

接口文档横贯各个端的研发人员，可是因为接口众多，细节不一，有时候理解起来并非那么容易，引发‘内战’也在所不免， 而且维护也是一大难题。

17 年项目使用markdown 文档, 项目大了, 18年转而引用RAP文档;

相似RAP文档管理系统，将接口文档进行在线维护，方便了前端和APP端人员查看进行对接开发 ，可是仍是存在如下几点问题：

• 文档是接口提供方手动导入的，静态文档,项目大查阅麻烦；
• 多人开发时,容易形成文档锁定,没法继续编写;
• 维护的难度不小。
• 后端开发人员编写重复,工做量大
• 确实接口测试,通常都是本身下载postman调试接口

Swagger的出现能够完美解决以上传统接口管理方式存在的痛点。

解放后端开发人员,全程自动生成,无需频繁切换,工具,一切都在java中;

本文介绍SpringBoot整合Swagger2的流程。

什么是Swagger

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

做用

1. 接口文档在线生成
2. 功能测试

实用语法

@Api：用在类上，说明该类的做用。

@ApiOperation：注解来给API增长方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增长说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，通常用于表达一个错误的响应信息

    l   code：数字，例如400

    l   message：信息，例如"请求参数没填好"

    l   response：抛出异常的类  

@ApiModel：描述一个Model的信息（通常用在请求参数没法使用@ApiImplicitParam注解进行描述的时候）

    l   @ApiModelProperty：描述一个model的属性

 

paramType：指定参数放在哪一个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不经常使用） form（不经常使用）
name：参数名
dataType：参数类型
required：参数是否必须传	true | false
value：说明参数的意思
defaultValue：参数的默认值

 

简单介绍完毕,开始正式组合搭建了

springboot + swagger 搭建

1. dependency引用

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
<!-- swagger2 加强UI ,拥有好看的界面, 和接口分组,排序等功能,如不引用可自行删除-->
<dependency>
                <groupId>com.github.xiaoymin</groupId>
                <artifactId>swagger-bootstrap-ui</artifactId>
                <version>1.8.7</version>
            </dependency>

 

2. config配置

package com.xxx.config;

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI  //第三方swagger加强API注解
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        /**
         * @Author wuxw
         * @Description //关于分组接口,可后期根据多模块,拆解为根据模块来管理API文档
         * @Date 10:18 2019/3/15
         * @Param []
         * @return springfox.documentation.spring.web.plugins.Docket
         **/
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("后台管理接口")
                .apiInfo(apiInfo())
                .host("localhost:8082")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XX项目API")
                .description("系统化信息化XX平台,为您提供最优质的服务")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }
}

3. 方法注释

划重点: 注解Controller接口方法时,务必指定@GetMappering,@PostMapping等, 不然swagger 会生成多个相同api的接口;

4.   访问入口

如未使用加强ui, 则访问路径为:  http://localhost:8080/swagger-ui.html  (默认)

加强UI 访问路径: http://localhost:8080/doc.html

其中, 若是使用加强ui, doc.html404 找不到的话, 可修改application类,重载指定方法实现;

package com.xx.xx;

import lombok.extern.slf4j.Slf4j;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Slf4j
@SpringBootApplication
@MapperScan("com.xx.xx.*.mapper")
public class SystemApplication  implements WebMvcConfigurer {

	public static void main(String[] args) {
		long beginTime = System.currentTimeMillis();
		SpringApplication.run(SystemApplication.class, args);
		long endTime = System.currentTimeMillis();
        log.error("-----------启动完毕---------;启动耗时(s):"+((endTime-beginTime)/1000));
	}

	/**
	 * @Author wuxw
	 * @Description implements WebMvcConfigurer 该接口,重写addResourceHandlers ,添加swagger2 UI doc样式
	 * @Date 9:49 2019/3/15
	 * @Param [registry]
	 * @return void
	 **/
	@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}

}

 默认UI界面

加强UI界面

其中, 展开页签功能 更是对开发者来讲, 可随意切换接口调试,很是的棒

 

推荐完毕

加强UI更多功能,欢迎访问官方文档

http://www.xiaominfo.com/swagger-bootstrap-ui/