step1.Spring boot接入swagger实在很简单,所以你应该是一个Spring mvc项目,然后又被改造之后需要向前端提供restful接口。
step2.添加swagger依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
以上两个依赖就够了。
step3.到swagger的github下载项目,把dist文件夹放到你的Spring mvc项目的webapps目录下,名字改成swagger
step4:设置你的servlet,反正既然是spring-mvc项目,你肯定已经搞了servlet对伐,在你的servlet 配置xml下,设置:
<mvc:resources mapping="/swagger/**" location="/swagger/"/>
<bean class="config.SwaggerController" />
这句话会让你的swagger资源请求不被拦截,注意文件夹的位置不能错啊。然后会把目前还没有写的(咦)swagger配置类注入。
在你的登录拦截器(如果有)配置下添加:
<mvc:exclude-mapping path="/swagger/**"/>
<mvc:exclude-mapping path="/v2/api-docs.do"/>
这两句话保证你的swagger在线接口不需要在线才能看。
step5.添加swaggerConfig,如下,直接抄吧,记得package也就是你需要在文档中显示的接口类所在的包,别搞错了:
package config;
import com.google.common.base.Predicates;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerController extends WebMvcConfigurationSupport {
public static final String SWAGGER_SCAN_BASE_PACKAGE = "controller.restful";
@Bean
public Docket customDocket() {
//
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)).build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
Contact contact = new Contact("", "", "");
return new ApiInfo("后台API接口",//大标题 title
"",//小标题
"",//版本
"",//termsOfServiceUrl
contact,//作者
"",//链接显示文字
"e"//网站链接
);
}
}
step5.重启项目,在项目地址上可以看到启动的swagger,
step6(可选).如果l你还需要提供离线文档给前端的话,在pom中添加build/plugins/plugin:
<plugin>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup-maven-plugin</artifactId>
<version>1.3.1</version>
<configuration>
<swaggerInput>http://localhost:8080/v2/api-docs.do</swaggerInput><!---swagger-api-json路径-->
<outputFile>src/docs/asciidoc/generated/swagger</outputFile><!---生成路径-->
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式-->
</config>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<!--asciidoc文件目录-->
<sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
<!---生成html的路径-->
<outputDirectory>docs/asciidoc/html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--导航栏在左-->
<toc>left</toc>
<!--显示层级数-->
<!--<toclevels>3</toclevels>-->
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
如上,两个plugin的地址别配错啊,不管是swgger的json输出地址还是导出文档的地址都不能错的哦。
swagger2markup会将我们的swagger导出json到指定路径,然后asciidoctor会将json转换成html格式的离线文档(也可以是其他格式啦)
调用maven run这两个依赖吧,顺序不能错哦:
导出的文档大概是这样:
二、swagger注解及最优实践
1. 强烈建议限制restful方法的接收请求类型为一种,如下所示
@RequestMapping(value = "/addRoleTask",method = RequestMethod.POST
2. 建议在controller上添加注解表名controller作用
@RestController
@RequestMapping("userTask")
@Api(tags ="用户任务关联接口")
public class UserTaskController extends BasicController
3. 建议在方法上添加注解标明方法作用
@ApiOperation(value = "添加角色--任务权限")
@RequestMapping(value = "/addRoleTask",method = RequestMethod.POST,produces = {"application/json;charset=UTF-8"})
public ResultVo<Integer> addRoleTask(@RequestBody AddRoleTaskVO addRoleTaskVO){
4. 建议使用dto封装前端请求及后端返回
5. 建议在dto字段上添加注解说明每个字段的用处,可以使用代码生成器做这个工作,直接把数据库的注释取出来即可
@ApiModelProperty("角色id")
@Column( name="role_id")
private String roleId;
6. 在生产环境禁用swagger的方法
使用
@Profile("dev")
在swaggerConfig上,可以限制其只能在开发环境下运行,对应的jetty配置如下:
<configuration>
<httpConnector>
<port>10160</port>
</httpConnector>
<systemProperties>
<systemProperty>
<name>spring.profiles.active</name>
<value>dev</value>
</systemProperty>
</systemProperties>
</configuration>
可以看到,只有当我们把这里的profile-active设成dev时,swagger才能正常运作。