Restful API文档生成工具——Swagger应用(注解方式的应用)

http://127.0.0.1:8099/api

一个完整的软件、系统、服务包括：
1. 可运行的系统
2. 代码、文档
3. 服务监控，告警
4. 服务治理、服务降级、服务熔断

......

 

今天我们简单说说文档这事，系统代码更新频繁，文档的管理一直都是个难点，别说文档了，代码注释更新维护都是难点，何况说文档。普遍大家都不愿意写注释，更别说写文档，何况是写别人代码的注释，文档。
如何更新维护文档，一直没有更好的方式，更多是项目中， 团队中的一些约束、规范吧，包括codereview方式。今天说的Swagger也不是最好的方式

 

文档分很多种，今天说的是 api文档——restful接口对应的api文档

今天主要写下 Swagger如何应用, Swagger的配置，直接参考代码吧 (talk is cheap, show me your code )

 

1. @EnableSwagger2 注解

@Configuration
@EnableSwagger2
public class Swagger2Configure {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
				.apis(RequestHandlerSelectors.basePackage("com.xxx.product.web.controller"))
				.paths(PathSelectors.any()).build();
	}

	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("xxxapi文档").description("xxx的API文档")
				.termsOfServiceUrl("http://127.0.0.1:8080/api").version("1.0").build();
	}

}

通过EnableSwagger2 注解，来生效 Swagger。

 

2.  @Api 
    @ApiOperation
    @ApiImplicitParams  注解 

@Api(tags = "xxxx")
@RestController
@RequestMapping
public class xxxxController {
 
	@ApiOperation(value = "查询xxx详情", notes = "xxx详情")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "planeId", value = "xxxId", required = true, dataType = "Long", paramType = "path", defaultValue = "") })
	@GetMapping(value = "/product/aaaa/{xxId}")
	public RestResponse<PlaneResponse> queryPlaneById(@PathVariable("xxId") Long xxId) {
            // ... ... 
	}

}

 

3. 看看 swagger生成的 api文档，访问下面地址看看

http://127.0.0.1:8080/v2/api-docs