打造一款适合自己的快速开发框架-集成swaggerui和knife4j

前言

Swaggerui自动生成接口文档,可以不需要频繁更新接口文档,保证接口文档与代码的一致。 knife4j是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验 。不过现在knife4j还是有一些坑，坐等作者后续优化完善。

开始动手

目录说明

只罗列需要新增或修改的文件

├── mldong-admin  管理端接口
    ├── src/main/java
      └──com.mldong.modules.sys
        └── controller 控制层
        	└── SysUserController.java
├── mldong-common  工具类及通用代码
	├── src/main/java
		└──com.mldong.common.config
			└── SwaggerConfig.java
	└── pom.xml
├── mldong-generator  代码生成器
└── mldong-mapper 持久层

文件说明

• mldong-common/pom.xml

<!--springboot-web-->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--swaggerui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
</dependency>
<!--knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
</dependency>

父工程已经配置有版本号了，但了为了方便复制，这里也暂留一份

<properties>
    <io.springfox-swagger2.version>2.7.0</io.springfox-swagger2.version>
	<swagger-knife.version>2.0.3</swagger-knife.version>
 </properties>

• mldong-common/src/main/java/com/mldong/common/config/SwaggerConfig.java

package com.mldong.common.config;

import io.swagger.annotations.ApiOperation;

import java.util.List;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import com.google.common.collect.Lists;

@Configuration
@EnableSwagger2
@Profile({"dev","test"}) // 只有开发环境和测试环境才会生效
public class SwaggerConfig implements WebMvcConfigurer {

	@Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
		// 这个是默认的swaggerui
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 这个是knife4j的ui
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
	
    @Bean
    public Docket adminApi() {
    	return new Docket(DocumentationType.SWAGGER_2)
    		.groupName("后台业务接口")
			.apiInfo(adminInfo())
            .select()
            //.apis(RequestHandlerSelectors.basePackage("com.mldong.modules"))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(security());
    }
    
    private ApiInfo adminInfo() {
    	return new ApiInfoBuilder()
        .title("接口文档-后台管理接口")
        .description("所有请求都使用请求正文json的方式-POST")
        .version("1.0")
        .build();
    }
    private List<ApiKey> security() {
    	// 这里配置请求策略-header["Auth-Token"]
    	return Lists.newArrayList(
    			new ApiKey("Auth-Token", "Auth-Token", "header")
    	);
   }
}

• mldong-admin/src/main/java/com/mldong/modules/sys/controller/SysUserController.java

package com.mldong.modules.sys.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import com.github.pagehelper.Page;
import com.mldong.modules.sys.entity.SysUser;
import com.mldong.modules.sys.service.SysUserService;

@RestController
@RequestMapping("/sys/user")
@Api(tags="sys-用户管理")
public class SysUserController {
	@Autowired
	private SysUserService sysUserService;
	/**
	 * 添加用户
	 * @param param
	 * @return
	 */
	@PostMapping("save")
	@ApiOperation(value="添加用户", notes="添加用户")
	public int save(@RequestBody SysUser param) {
		return sysUserService.save(param);
	}
	/**
	 * 更新用户
	 * @param param
	 * @return
	 */
	@PostMapping("update")
	@ApiOperation(value="更新用户", notes="更新用户")
	public int update(@RequestBody SysUser param) {
		return sysUserService.update(param);
	}
	/**
	 * 删除用户
	 * @param param
	 * @return
	 */
	@PostMapping("delete")
	@ApiOperation(value="删除用户", notes="删除用户")
	public int delete(@ApiParam(value="用户id")Long id) {
		return sysUserService.delete(id);
	}
	/**
	 * 通过id获取用户
	 * @param param
	 * @return
	 */
	@GetMapping("get")
	@ApiOperation(value="通过id获取用户", notes="通过id获取用户")
	public SysUser get(@ApiParam(value="用户id",required=true)Long id) {
		return sysUserService.get(id);
	}
	/**
	 * 分页查询用户列表
	 * @param param
	 * @return
	 */
	@GetMapping("list")
	@ApiOperation(value="分页查询用户列表", notes="分页查询用户列表")
	public Page<SysUser> list(SysUser param, @ApiParam(value="第n页，默认1")@RequestParam(defaultValue="1")Integer pageNum, @ApiParam(value="每页大小，默认10")@RequestParam(defaultValue="10")int pageSize) {
		return sysUserService.list(param, pageNum, pageSize);
	}
}

启动运行项目

MldongAdminApplication.java

右键->Run As -> Java Application

访问页面

• swaggerui文档

http://localhost:18080/swagger-ui.html

• knife4j文档

http://localhost:18080/doc.html

如项目启动正常，访问页面会看到对应的接口文档。

截图，略。

swaggerui常用注解说明

注解	作用域	说明
@Api(tags="sys-用户管理")	类	表示标识这个类是swagger的资源
@ApiOperation(value="添加用户", notes="添加用户"	方法	表示一个http请求的操作
@ApiParam(value="用户id",required=true)	用于方法，参数，字段说明	表示对参数的添加元数据（说明或是否必填等）
@ApiModel(value="用户实体")	类	表示对类进行说明，用于参数用实体类接收
@ApiModelProperty(value="用户名")	用于方法，字段	表示对model属性的说明或者数据操作更改
@ApiIgnore()	用于类，方法，方法参数	表示这个方法或者类被忽略
@ApiImplicitParam()	用于方法	表示单独的请求参数
@ApiImplicitParams()	用于方法	包含多个 @ApiImplicitParam

项目源码地址

• 后端

gitee.com/mldong/mldo…

• 前端

gitee.com/mldong/mldo…

相关文章

打造一款适合自己的快速开发框架-先导篇

打造一款适合自己的快速开发框架-后端脚手架搭建

打造一款适合自己的快速开发框架-集成mapper