优雅的REST APIs文档管理

最新推荐文章于 2024-10-28 19:03:38 发布

原创最新推荐文章于 2024-10-28 19:03:38 发布 · 759 阅读

1 ·

CC 4.0 BY-SA版权

文章标签：

#api #文档管理 #swagger #springmvc

api管理专栏收录该内容

3 篇文章

订阅专栏

本文介绍如何在SpringMVC项目中集成Swagger，通过详细步骤和代码示例，帮助开发者快速实现API文档自动生成，提升前后端开发效率。

Swagger应该是最受欢迎的REST APIs文档管理工具之一，帮助我们更好的实现“前后端分离”。

Swagger 提供了一个具有互动性的API控制台，解决了传统手写文档的繁琐、对于服务端和Web前端以及移动端的对接效率得到极大提高。

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

SpringMVC集成Swagger 2.7.0

pom.xml

        <!-- swagger api  -->	
		<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>

package org.easy.core.config;

import org.springframework.context.annotation.Bean;

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;

/**
 * @ClassName SwaggerConfig
 * @Description api 管理
 * @author Cheng.Wei
 * @date 2017年8月17日 下午3:19:37
 * 
 */
@EnableSwagger2
public class SwaggerConfig {

	@Bean
	public Docket platformApi() {
		return new Docket(DocumentationType.SWAGGER_2).groupName("full-platform").select().apis(RequestHandlerSelectors.any()).paths(PathSelectors.any()).build().apiInfo(apiInfo())
				.forCodeGeneration(true);
	}

	private static ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("easy-api").description("easy-api文档信息")
				.contact(new Contact("Cheng.Wei", "tencent://message/?uin=930098011", "dhweicheng@163.com")).license("Apache License Version 2.0")
				.licenseUrl("https://github.com/abelsilva/SwaggerWCF/blob/master/LICENSE").version("1.0").build();
	}

}

配置文件

    <!-- API相关配置 -->
    <bean class="org.easy.core.config.SwaggerConfig"/>
    <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**" />

在控制器下对应的请求方法上使用@ApiOperation

@ApiOperation(value=“接口说明”, httpMethod = "接口请求方式”, response = "接口返回参数类型”, notes = “接口发布说明”)其他参考源码；

使用@ApiImplicitParams

    @RequestMapping(value = "/user", method = RequestMethod.POST)
    @ApiOperation(value = "用户注册", response = ModelAndView.class, notes = "用户注册表单参数", produces = org.springframework.http.MediaType.APPLICATION_JSON_VALUE)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "账号不超过16位", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "password", value = "密码不超过16位", required = true, dataType = "String", defaultValue = "123456", paramType = "query"),
            @ApiImplicitParam(name = "phone", value = "手机号", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "nickname", value = "姓名", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "roleId", value = "角色ID", required = true, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "locked", value = "角色ID", required = true, dataType = "boolean", paramType = "query"),
            @ApiImplicitParam(name = "departmentId", value = "部门ID", required = false, dataType = "Integer", paramType = "query")
    }) public ModelAndView signUp(HttpServletRequest request){ //TODO }

或者对数据传送对象注解

/**
 * 
 * @ClassName RoleQuery
 * @Description 角色信息查询对象
 * 				翻页参数{@link org.easy.core.base.PageParam;}
 * @author Cheng.Wei
 * @date 2017年10月5日 上午10:02:40
 *
 */
public class RoleQuery extends PageParam implements Serializable {
	private static final long serialVersionUID = 4130429963465365573L;
	@ApiParam(value = "角色名称")
	private String name;
	@ApiParam(value = "状态")
	private Boolean locked;	
	
}

	@ApiOperation(value = "查询", notes = "角色查询", produces = org.springframework.http.MediaType.APPLICATION_JSON_VALUE)
	@RequestMapping(method=RequestMethod.GET)
	public ModelAndView query(RoleQuery query){
		//TODO
		return getResultPage(new PageBean<>());
	}

启动服务器：访问 http://127.0.0.1:8080/项目名称/swagger-ui.html

方式二比方式一简洁、方式一比方式二灵活，根据需要选择。