JavaWeb项目中集成Swagger API文档

来源：互联网发布：淘宝联盟推广位是什么编辑：程序博客网时间：2024/05/29 10:29

0 本文主要涉及

在基于Spring和SpringMVC的前后端分离的JavaWeb项目中生成Swagger API文档（使用SpringFox来实现）。

1 SpringFox和Swagger简介

结合SpringFox通过注解的形式自动生成Swagger API文档（HTML页面形式），该文档还具有简单的接口调试功能。
官网：http://springfox.github.io/springfox/

2 SpringFox配置集成

0 依赖配置

<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>

1 SpringBean配置

通过JavaConfig形式

@Configuration@EnableWebMvc@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket myDocket() {        Docket docket = new Docket(DocumentationType.SWAGGER_2);        ApiInfo apiInfo = new ApiInfoBuilder()                .title("API接口文档")                .description("")                .contact(new Contact("", "", ""))                .version("1.0")                .build();        docket.apiInfo(apiInfo);        //设置只生成被Api这个注解注解过的Ctrl类中有ApiOperation注解的api接口的文档        docket.select().apis(RequestHandlerSelectors.withClassAnnotation(Api.class)).apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();        return docket;    }}

在SpringMVC的Bean中写入资源路径映射

 <mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"/> <mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars/"/>

如果项目使用了Shiro控制页面访问权限需要在过滤器中加入以下配置，方便文档使用

<!--swagger接口文档-->/swagger*/**=anon/v2/**=anon/webjars/**=anon

3 Swagger使用示例

@RestController@RequestMapping("/user")@Api(tags = "UserinfoCtrl", description = "用户信息相关")public class UserInfoCtrl{    @Autowired    private UserInfoService userInfoService;    @RequestMapping("/getInfo")    @ApiOperation(value = "获取用户信息", httpMethod = "GET", notes = "显示用户信息，不显示密码")    public Object getInfo() throws MyMessageException    {        return userInfoService.getInfo();    }    @RequestMapping("/login")    @ApiOperation(value = "登录", httpMethod = "POST", notes = "说明。。。")    @ApiImplicitParams({         @ApiImplicitParam(name = "name", value = "用户名", required = true, paramType = "query", dataType = "String"),         @ApiImplicitParam(name = "password", value = "密码(MD5)", required = true, paramType = "query", dataType = "String"),         @ApiImplicitParam(name = "rememberMe", value = "是否记住登录状态", defaultValue = "false", paramType = "query", dataType = "boolean"),})    public Object login(@Valid LoginVO user, @RequestParam(defaultValue = "false") Boolean rememberMe, HttpServletRequest request) throws Exception    {        //。。。    }}

生成的文档可在http://host地址:端口/项目名/swagger-ui.html#/中看到

阅读全文

0 0