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

最新推荐文章于 2024-10-11 21:08:09 发布

weixin_34387284

最新推荐文章于 2024-10-11 21:08:09 发布

阅读量3.7k

点赞数 2

文章标签： ui java c#

原文链接：https://my.oschina.net/java1314/blog/3023010

版权

2019独角兽企业重金招聘Python工程师标准>>>

前言

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

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

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

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

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

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

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

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

什么是Swagger

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

作用

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

实用语法

@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/");
	}

}