springmvc系列之 ------------- swagger restful API接口注释

refer：

Swagger-API文档生成框架的基本使用_了无牵挂者忘生，心有所爱者忘死-CSDN博客

Swagger Documentation

关于springfox的介绍网上很多，以及它能做些什么网上也很多，但是我还是打算写一下，但是这里先不写，后面补上。这里我们先看怎么使用，先用起来，后面再来看它的功能。

首先，这是基于maven的总结，如果想指导Gradle那么就自己看官方文档

1、pom依赖

		<!-- begin swagger -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.9.2</version>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.9.2</version>
		</dependency>
		<!-- end swagger -->

2、简单的swagger的配置

@Configurable
public class SwaggerConfig {

	@Bean
	public Docket docket() {
		// 创建docket（摘要），需要指定文档类型
		return new Docket(DocumentationType.SPRING_WEB)
				// 返回一个ApiSelectorBuilder，就是API选择器构造器，用来指定selector，可以是apis/paths
				.select()
				// 使用RequestHandlerSelectors，就是请求处理器选择器
				.apis(RequestHandlerSelectors.any())
				// 使用PathSelectors，就是路径选择器
				.paths(PathSelectors.any())
				// 构造docket
				.build();
	}
}

3、有安全校验的swagger配置

@Configurable
public class SwaggerConfig {

	@Bean
	public Docket docket() {
		// 创建docket（摘要），需要指定文档类型
		return new Docket(DocumentationType.SPRING_WEB)
				// 返回一个ApiSelectorBuilder，就是API选择器构造器，用来指定selector，可以是apis/paths
				.select()
				// 使用RequestHandlerSelectors，就是请求处理器选择器
				.apis(RequestHandlerSelectors.any())
				// 使用PathSelectors，就是路径选择器
				.paths(PathSelectors.any())
				// 构造docket
				.build()
				//
				.securitySchemes(Arrays.asList(securityScheme()))
				//
				.securityContexts(Arrays.asList(securityContext()));
	}

	private final String CLIENT_ID = null;
	private final String CLIENT_SECRET = null;
	private final String AUTH_SERVER = null;

	@Bean
	public SecurityConfiguration security() {
		return SecurityConfigurationBuilder
				//
				.builder()
				//
				.clientId(CLIENT_ID)
				//
				.clientSecret(CLIENT_SECRET)
				//
				.scopeSeparator(" ")
				//
				.useBasicAuthenticationWithAccessCodeGrant(true)
				//
				.build();
	}

	AuthorizationScope[] scopes = {
			//
			new AuthorizationScope("read", "for read operations"),
			//
			new AuthorizationScope("write", "for write operations"),
			//
			new AuthorizationScope("foo", "Access foo API") };

	private SecurityScheme securityScheme() {
		GrantType grantType = new AuthorizationCodeGrantBuilder()
				//
				.tokenEndpoint(new TokenEndpoint(AUTH_SERVER + "/token", "oauthtoken"))
				//
				.tokenRequestEndpoint(new TokenRequestEndpoint(AUTH_SERVER + "/authorize", CLIENT_ID, CLIENT_ID))
				//
				.build();

		return new OAuthBuilder().name("spring_oauth")
				//
				.grantTypes(Arrays.asList(grantType))
				//
				.scopes(Arrays.asList(scopes))
				//
				.build();
	}

	private SecurityContext securityContext() {
		return SecurityContext
				//
				.builder()
				//
				.securityReferences(Arrays.asList(new SecurityReference("spring_oauth", scopes)))
				//
				.forPaths(PathSelectors.regex("/foos.*"))
				//
				.build();
	}

}

4、注释的作用

@Api(description = "流程定义接口") ：该注释用在controller上，说明controller的作用

@ApiOperation(value = "通过json文件创建流程定义") ：该注释用在方法上，说明方法的作用

@ApiImplicitParams({ @ApiImplicitParam(name = "bpmn", value = "流程定义的json文件") }) ：该注释用在方法上，说明参数的意义

wiremock

参考文档：

springfox官方文档：Springfox Reference Documentation