爲做好的項目寫個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美化的文檔界面：
