写在前面的，以下是https://github.com/macrozheng/mall-learning 对应的学习
1.前后端分离情况下，还是感觉有具体的页面操作比较安心
2.另外 Swagger-UI 是用来写在线API文档的(很关键，小型可以快速开发，对应Controller层接口改变，对应也相对应改变)，不然要用对应文档第三方去写接口文档，语雀似乎是最近开放出来的，可以去了解一下
====================================================
进入实际操作
Swagger-UI 是HTML,javascript，CSS的一个集合，可以动态根据注解生成在线API文档
常用注解
1.@Api 用于修饰Controller类，生成Contriller的相关文档信息
2.@ApiOperation: 用于修饰Controller类中的方法，生成接口方法相关文档信息
3.@ApiParam : 用于修饰接口的参数，生成接口参数相关文档信息 (通常接受前端传值为vo最佳，如果单个或者个别比较少，创建一个vo类专门接受这类参数)
4.@ApiModelProperty : 用于修饰实体类的属性，当实体类是请求参数或返回结果时，直接生成相关文档信息
=========================================
配置部分
<!--Swagger-UI API文档生产工具-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
====================================================
然后是 Swagger-UI的java配置
有三个不同的选择
A.生成指定包下面的类的API文档
B.生成有指定注解的类API文档
C.生成有指定注解的方法的API文档
具体代码
package com.macro.mall.tiny.config;
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;
/**
* Swagger2API文档的配置
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包下controller生成API文档
.apis(RequestHandlerSelectors.basePackage("com.macro.mall.tiny.controller"))
//为有@Api注解的Controller生成API文档
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//为有@ApiOperation注解的方法生成API文档
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SwaggerUI演示")
.description("mall-tiny")
.contact("macro")
.version("1.0")
.build();
}
}
======================
然后是controller层添加Swagger注解
这里先是类加上注解 然后对应方法加上注解
这里已经可以满足一般的API文档注解了
=========================================================
进阶版本
结合之前的Mybatis Generator注释的生成规则
CommentGenerator为Mybatis Generator 的自定义注解生成器，修改addFieldComment方法使其生成Swagger的@ApiModelProperty注解来取代原来的方法注解，添加addJavaFileCOmment方法，使其能在import中导入@ApiModelProperty，否则需要手动导入该类，便于需要生成大量实体类场景
对应代码
package com.macro.mall.tiny.mbg;
import org.mybatis.generator.api.IntrospectedColumn;
import org.mybatis.generator.api.IntrospectedTable;
import org.mybatis.generator.api.dom.java.CompilationUnit;
import org.mybatis.generator.api.dom.java.Field;
import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
import org.mybatis.generator.internal.DefaultCommentGenerator;
import org.mybatis.generator.internal.util.StringUtility;
import java.util.Properties;
/**
* 自定义注释生成器
* Created by macro on 2018/4/26.
*/
public class CommentGenerator extends DefaultCommentGenerator {
private boolean addRemarkComments = false;
private static final String EXAMPLE_SUFFIX="Example";
private static final String API_MODEL_PROPERTY_FULL_CLASS_NAME="io.swagger.annotations.ApiModelProperty";
/**
* 设置用户配置的参数
*/
@Override
public void addConfigurationProperties(Properties properties) {
super.addConfigurationProperties(properties);
this.addRemarkComments = StringUtility.isTrue(properties.getProperty("addRemarkComments"));
}
/**
* 给字段添加注释
*/
@Override
public void addFieldComment(Field field, IntrospectedTable introspectedTable,
IntrospectedColumn introspectedColumn) {
String remarks = introspectedColumn.getRemarks();
//根据参数和备注信息判断是否添加备注信息
if(addRemarkComments&&StringUtility.stringHasValue(remarks)){
// addFieldJavaDoc(field, remarks);
//数据库中特殊字符需要转义
if(remarks.contains("\"")){
remarks = remarks.replace("\"","'");
}
//给model的字段添加swagger注解
field.addJavaDocLine("@ApiModelProperty(value = \""+remarks+"\")");
}
}
/**
* 给model的字段添加注释
*/
private void addFieldJavaDoc(Field field, String remarks) {
//文档注释开始
field.addJavaDocLine("/**");
//获取数据库字段的备注信息
String[] remarkLines = remarks.split(System.getProperty("line.separator"));
for(String remarkLine:remarkLines){
field.addJavaDocLine(" * "+remarkLine);
}
addJavadocTag(field, false);
field.addJavaDocLine(" */");
}
@Override
public void addJavaFileComment(CompilationUnit compilationUnit) {
super.addJavaFileComment(compilationUnit);
//只在model中添加swagger注解类的导入
if(!compilationUnit.isJavaInterface()&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){
compilationUnit.addImportedType(new FullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME));
}
}
}
出现的效果是
然后是运行起来，看具体效果
接口地址:http://localhost:8080/swagger-ui.html
基本总结，对应文字类说明在实体类中生成，尽量我们后端可以让前端知道，他需要调用什么，以及调用的大概字段意思
