一:swagger是什么?
1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。
方法一:使用第三方依赖(最简单的方法)
1、在pom.xml文件中添加第三方swagger依赖()
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.7.0.RELEASE</version>
</dependency>
View Code
2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解,就可以直接使用啦。
3、https://github.com/SpringForAll/spring-boot-starter-swagger这是GitHub上这个swagger依赖实现的项目,里面有详细的讲解。
方法二:使用官方依赖
1、在pom.xml文件中添加swagger相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox-version}</version>
</dependency>
View Code
第一个是API获取的包,第二是官方给出的一个ui界面。这个界面可以自定义,默认是官方的,对于安全问题,以及ui路由设置需要着重思考。
2、swagger的configuration
需要特别注意的是swagger scan base package,这是扫描注解的配置,即你的API接口位置。
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台 APIs")
.description("服务:发布为daocke镜像,权限管理,用户管理,页面管理,日志 后台")
.termsOfServiceUrl("http://192.168.103.198:10070/platformgroup/ms-admin")
.contact("程序猿DD")
.version("1.0")
.build();
}
}
View Code
三、具体使用
1、在API上做一些声明
@RequestMapping("/swagger/test/map")
@ApiOperation(value="xxxx", tags = "xxxx")
@ApiImplicitParams({
@ApiImplicitParam(name="name", dataType = "string", value = "only return models...")
})
@ApiResponses(value = {
@ApiResponse(code = 200, message="Indicates ..."),
@ApiResponse(code = 404, message = "not found error")
})
public Result<String> testSwaggerMap(Map map){
return null;
}
View Code
https://blog.csdn.net/xtj332/article/details/80595768
如果项目文档访问出现404,参照上面的地址查看原因
https://www.cnblogs.com/mingxiaoyue/p/8877429.html
如果样式出现问题请参考上面查看原因
我在实践中遇到只有swagger页面头部的情况,没有一个api显示,经过查证之后发现是shiro安全框架拦截了,将其注释掉之后就好了。具体原因还没有确定,等待有时间查一下,又或许没法解决,反正上线的时候可以将enable改为false,然后开启shiro等安全框架的拦截。