[java]构建在线restfulAPI文档之swagger2
2017-09-04 17:46
323 查看
springfox定义: Automated
JSON API documentation for API's built with Spring http://springfox.io
Swagger2 是 springfox 下面的一个开源项目,地址: https://github.com/springfox/springfox
使用 Swagger2
1: 导入Swagger2核心库和Swagger2 UI库
2: 配置 Docket bean,交给spring 容器管理
官方文档地址:http://springfox.github.io/springfox/docs/current/#development-environment
@Bean
编写User API 并使用注解
访问http://localhost:8080/swagger-ui.html 并调用API
常用相关注解
JSON API documentation for API's built with Spring http://springfox.io
1. Introduction The Springfox suite of java libraries are all about automating the generation of machine and human readable specifications for JSON APIs written using the spring family of projects. Springfox works by examining an application, once, at runtime to infer API semantics based on spring configurations, class structure and various compile time java Annotations. 1.1. History Springfox has evolved from a project originally created by Marty Pitt and was named swagger-springmvc. Much kudos goes to Marty. 1.2. Goals To extend support for a number of the evolving standards targeted at JSON API specification and documentation such as: swagger, RAML and jsonapi. To extend support for spring technologies other than spring webmvc Philosophically, we want to discourage using (swagger-core) annotations that are not material to the service description at runtime. For e.g. the jackson annotations should always trump or have more weight than @ApiModelProperty or for e.g. @NotNull or specifying @RequestParam#required should always win. Annotations are to to be used only to supplement documentation or override/tweak the resulting spec in cases where its not possible to infer service/schema characteristics.
Swagger2 是 springfox 下面的一个开源项目,地址: https://github.com/springfox/springfox
使用 Swagger2
1: 导入Swagger2核心库和Swagger2 UI库
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version>
2: 配置 Docket bean,交给spring 容器管理
官方文档地址:http://springfox.github.io/springfox/docs/current/#development-environment
@Configuration @EnableSwagger2 public class Config{
@Bean
public Docket petApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build() .pathMapping("/") .directModelSubstitute(LocalDate.class, String.class) .genericModelSubstitutes(ResponseEntity.class) .alternateTypeRules( newRule(typeResolver.resolve(DeferredResult.class, typeResolver.resolve(ResponseEntity.class, WildcardType.class)), typeResolver.resolve(WildcardType.class))) .useDefaultResponseMessages(false) .globalResponseMessage(RequestMethod.GET, newArrayList(new ResponseMessageBuilder() .code(500) .message("500 message") .responseModel(new ModelRef("Error")) .build())) .securitySchemes(newArrayList(apiKey())) .securityContexts(newArrayList(securityContext())) .enableUrlTemplating(true) .globalOperationParameters( newArrayList(new ParameterBuilder() .name("someGlobalParameter") .description("Description of someGlobalParameter") .modelRef(new ModelRef("string")) .parameterType("query") .required(true) .build())) .tags(new Tag("Pet Service", "All apis relating to pets")) .additionalModels(typeResolver.resolve(AdditionalModel.class)) ; }
Configuration explained
编写User API 并使用注解
@ApiOperation(value = "查询用户",notes = "用户列表查询") @GetMapping public SaveUserModel findUser( @ApiParam(value = "用户状态 normal |not Normal", required = true) @RequestParam(name="status", defaultValue="normal") String status) { return new SaveUserModel("xiaoming","123445"); } @ApiOperation(value = "创建用户",notes = "新增一个用户") @PostMapping public SaveUserModel findPetsByStatus( @RequestBody SaveUserModel model) { return new SaveUserModel("xiaoming","123445"); }
访问http://localhost:8080/swagger-ui.html 并调用API
常用相关注解
@ApiParam#value() @ApiImplicitParam#value() @ApiModelProperty#value() @ApiOperation#value() @ApiOperation#notes() @RequestParam#defaultValue() @RequestHeader#defaultValue()
相关文章推荐
- 基于spring-boot使用Swagger构建restful api文档
- SpringBoot入门——使用Swagger构建Restful API文档
- java ThumbnailAPI在线文档
- SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
- Java各版本在线及离线JDK API——如何制作CHM文档
- ASP.NET WebApi 中使用swagger 构建在线帮助文档
- 查阅 JDK 6.0 API 在线中文文档 JavaTM 2 Platform Standard Edition 6
- Swagger: 一个restful接口文档在线生成+功能测试软件
- Spring Boot中使用Swagger2构建RESTful API文档
- springboot利用swagger构建api文档
- spring boot / cloud (三) 集成springfox-swagger2构建在线API文档
- 关于java web restful api文档的重新探索
- spring-boot整合swagger生成在线api文档
- SpringBoot&Swagger构建REST API并生成API文档
- swagger:API在线文档自动生成框架
- SwaggerUI+SpringMVC——构建RestFulAPI的可视化界面
- 在Spring中使用Springfox和swagger生成restful风格的API文档
- SpringBoot中使用Swagger生成RESTful规范API文档
- Swagger 一款RESTFUL接口的文档在线自动生成+功能测试功能软件
- jersey+swagger,构建api文档平台