为做好的项目写个API文档，传统方式太麻烦和费时间，于是在网上看到了swagger2在线api生成，决定使用这个（swagger有两种不同的版本，一个是swagger，一个是springfox的swagger2，我使用的是swagger2）。在配置Swagger2的时候出现访问时界面空白的坑，刚开始以为是配置的swagger-ui版本不兼容，还有说是与Spring版本不兼容，于是试了多个版本之后依然无法访问，后看到配置类中有的地方可以改动，于是是这改动配置类，还有把静态资源页面放在resouces新建的META-INF目录下的resouces里，文件在你使用相应的版本的叫jar包里找（把jar包解压或者去他的网站里下对应版本的）。
我的Spring版本是2.1.6
1.使用的swagger2的pom：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger.core.v3/swagger-annotations -->
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-annotations</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-models</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.5</version>
</dependency>
2.我的Swagger2配置类：
/** 在线接口文档
* @projectname yunju
* @author GEEKCJJ
* @date 2019年8月5日 上午10:53:56
* @description:
*
*/
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUi
//@Import(BeanValidatorPluginsConfiguration.class)
/**
* 将Swagger2 的swagger-ui.html加入资源路径下,否则Swagger2静态页面不能访问。要想使资源能够访问，可以有两种方法
* 一：需要配置类继承WebMvcConfigurationSupport 类，实现addResourceHandlers方法。
* 但是实现了WebMvcConfigurationSupport以后，Spring Boot的 WebMvc自动配置就会失效，具体表现比如访问不到
* 静态资源（js，css等）了，这是因为WebMvc的自动配置都在WebMvcAutoConfiguration类中，但是类中有这个注解
* @ConditionalOnMissingBean({WebMvcConfigurationSupport.class})，意思是一旦在容器中检测到
* WebMvcConfigurationSupport这个类，WebMvcAutoConfiguration类中的配置都不生效。
* 所以一旦我们自己写的配置类继承了WebMvcConfigurationSupport，相当于容器中已经有了WebMvcConfigurationSupport，
* 所有默认配置都不会生效，都得自己在配置文件中配置。
* 二：继承WebMvcConfigurer接口，这里采用此方法 网上有人说使用该方法会导致date编译等问题，可能在配置文件中得到解决，
* 本人没有碰到，不多做解释
* @param registry
*/
//我使用继承WebMvcConfigurationSupport类
public class SwaggerConfig extends WebMvcConfigurationSupport{//implements WebMvcConfigurer
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.mk.mkqy.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXXX API 接口文档")
.description("XXXX")
.termsOfServiceUrl("http://XXXX.XXX/")
.contact(new Contact("Maike","http://XXXX.XXX/","[email protected]"))
.version("1.0")
.build();
}
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
我把jar包里META-INF中resources中的html放在resources下新建的META-INF中的resources：
3.在controller中
@RestController
@Api(tags="查看文章",value="查看我的文章")
public class ArticleController extends BaseController{
@Resource
private ArticleMapper articleMapper;
@ApiOperation(value="我的个人中心", notes="查看我发布的文章")
@RequestMapping("querySelfArticle")
public ResponseVo<List<Article>> querySelfArticle(HttpSession session){
CustomerLogin login =getCurrentUser(session);
String customId=login.getCustomerId();
Wrapper<Article> wrapper=new QueryWrapper<>();
((QueryWrapper<Article>) wrapper).eq("customer_id",customId);
//返回一个list集合
List<Article> articles=articleMapper.selectList(wrapper);
return ResponseVo.response(200,"请求成功",articles);
}
}
4.另外我用了美化文档的swagger-bootstrap-ui这个pom文件，里面的doc.html就是从swagger-bootstrap-ui提取的，这样就好看也好整理成pdf和doc文档。swagger-bootstrap-ui里面提供markdown形式的API文档。
swagger-ui的界面：
bootstrapui美化的文档界面：
