寫在前面的视乐，以下是https://github.com/macrozheng/mall-learning?對應(yīng)的學(xué)習(xí)
1.前后端分離情況下兔辅，還是感覺有具體的頁面操作比較安心
2.另外 Swagger-UI 是用來寫在線API文檔的(很關(guān)鍵遥缕，小型可以快速開發(fā)坤学，對應(yīng)Controller層接口改變浮梢，對應(yīng)也相對應(yīng)改變)握巢，不然要用對應(yīng)文檔第三方去寫接口文檔抹腿，語雀似乎是最近開放出來的岛请，可以去了解一下
====================================================
進(jìn)入實際操作
Swagger-UI 是HTML,javascript，CSS的一個集合警绩，可以動態(tài)根據(jù)注解生成在線API文檔
常用注解
1.@Api? 用于修飾Controller類崇败，生成Contriller的相關(guān)文檔信息
2.@ApiOperation: 用于修飾Controller類中的方法，生成接口方法相關(guān)文檔信息
3.@ApiParam : 用于修飾接口的參數(shù)肩祥，生成接口參數(shù)相關(guān)文檔信息 (通常接受前端傳值為vo最佳后室，如果單個或者個別比較少，創(chuàng)建一個vo類專門接受這類參數(shù))
4.@ApiModelProperty : 用于修飾實體類的屬性混狠，當(dāng)實體類是請求參數(shù)或返回結(jié)果時岸霹，直接生成相關(guān)文檔信息
=========================================
配置部分
<!--Swagger-UI API文檔生產(chǎn)工具-->
<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()
? ? ? ? ? ? ? ? //為當(dāng)前包下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注解
這里先是類加上注解 然后對應(yīng)方法加上注解
這里已經(jīng)可以滿足一般的API文檔注解了
=========================================================
進(jìn)階版本
結(jié)合之前的Mybatis Generator注釋的生成規(guī)則
CommentGenerator為Mybatis Generator 的自定義注解生成器，修改addFieldComment方法使其生成Swagger的@ApiModelProperty注解來取代原來的方法注解将饺，添加addJavaFileCOmment方法贡避，使其能在import中導(dǎo)入@ApiModelProperty，否則需要手動導(dǎo)入該類予弧，便于需要生成大量實體類場景
對應(yīng)代碼
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";
? ? /**
? ? * 設(shè)置用戶配置的參數(shù)
? ? */
? ? @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();
? ? ? ? //根據(jù)參數(shù)和備注信息判斷是否添加備注信息
? ? ? ? if(addRemarkComments&&StringUtility.stringHasValue(remarks)){
//? ? ? ? ? ? addFieldJavaDoc(field, remarks);
? ? ? ? ? ? //數(shù)據(jù)庫中特殊字符需要轉(zhuǎn)義
? ? ? ? ? ? if(remarks.contains("\"")){
? ? ? ? ? ? ? ? remarks = remarks.replace("\"","'");
? ? ? ? ? ? }
? ? ? ? ? ? //給model的字段添加swagger注解
? ? ? ? ? ? field.addJavaDocLine("@ApiModelProperty(value = \""+remarks+"\")");
? ? ? ? }
? ? }
? ? /**
? ? * 給model的字段添加注釋
? ? */
? ? private void addFieldJavaDoc(Field field, String remarks) {
? ? ? ? //文檔注釋開始
? ? ? ? field.addJavaDocLine("/**");
? ? ? ? //獲取數(shù)據(jù)庫字段的備注信息
? ? ? ? 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注解類的導(dǎo)入
? ? ? ? if(!compilationUnit.isJavaInterface()&&!compilationUnit.getType().getFullyQualifiedName().contains(EXAMPLE_SUFFIX)){
? ? ? ? ? ? compilationUnit.addImportedType(new FullyQualifiedJavaType(API_MODEL_PROPERTY_FULL_CLASS_NAME));
? ? ? ? }
? ? }
}
出現(xiàn)的效果是
然后是運行起來刮吧，看具體效果
接口地址:http://localhost:8080/swagger-ui.html
基本總結(jié)，對應(yīng)文字類說明在實體類中生成掖蛤，盡量我們后端可以讓前端知道杀捻，他需要調(diào)用什么，以及調(diào)用的大概字段意思
