[java]构建在线restfulAPI文档之swagger2

springfox定义: Automated 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库

		
			io.springfox
			springfox-swagger2
			2.6.1
		

		
		
			io.springfox
			springfox-swagger-ui
			2.6.1

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