swagger

主要是为后端服务的接口文档，懒人必备，swagger就是一款让你更好的书写API文档的框架。
其他的框架有阿里爸爸推出 Rap ，感兴趣的可以自己了解一下。
本文主要基于springboot，要先了解下springboot；

开始

Maven

本项目基于maven
springboot pom 中添加

  <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
            <version>2.5.0</version>
            <scope>test</scope>
        </dependency>

启动

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * @author Dwxqnswxl
 */
@EnableAutoConfiguration
@SpringBootApplication(scanBasePackages = "com.example")
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

配置

import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Description
 *
 * @Author : huangjinxing
 * @Email : hmm7023@gmail.com
 * @Date : 2018/10/24 11:10
 * @Version :
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket swaggerSpringMvcPlugin() {
        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    @Bean
    public ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口列表 v1.1.0")
                .description("接口测试")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact(new Contact("HUANGJINXING","www.dwxqnswxl.cn","hmm7023@gmail.com"))
                .version("1.1.0")
                .build();
    }

}

Controller

package com.example.controller;

import com.example.bean.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.async.DeferredResult;

import java.util.HashMap;
import java.util.Map;

/**
 * Description
 *
 * @Author : huangjinxing
 * @Email : hmm7023@gmail.com
 * @Date : 2018/10/24 11:12
 * @Version :
 */
@Api()
@RestController
@RequestMapping("/demoController")
public class DemoController {

    private static final Logger log = LoggerFactory.getLogger(DemoController.class);

    public static final String RET_CODE = "retCode";
    public static final String RET_MSG = "retMsgo";

    @ApiOperation(value = "新增用户", notes = "新增注册")
    @PostMapping(value = "/createUser", consumes = MediaType.APPLICATION_JSON_VALUE)
    public DeferredResult createUser(@RequestBody User user) {
        log.info("createUser:::" , user.toString());
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "新增成功.");
        deferredResult.setResult(map);
        return deferredResult;
    }

    @ApiOperation(value = "修改用户", notes = "修改用户")
    @PostMapping(value = "/updateUser", consumes = MediaType.APPLICATION_JSON_VALUE)
    public DeferredResult updateUser(@RequestBody User user) {
        log.info("updateUser:::" , user.toString());
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "修改成功.");
        deferredResult.setResult(map);
        return deferredResult;

    }

    @ApiOperation(value = "删除用户", notes = "删除用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
    })
    @DeleteMapping(value = "/deleteUser")
    public DeferredResult deleteUser(@RequestParam("userId") String userId) {
        log.info("deleteUser:::" , userId);
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "删除成功.");
        deferredResult.setResult(map);
        return deferredResult;
    }

    @ApiOperation(value = "查询用户", notes = "查询用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
    })
    @GetMapping(value = "/queryUser")
    public DeferredResult queryUser(@RequestParam("userId") String userId) {
        log.info("queryUser:::" , userId);
        DeferredResult deferredResult = new DeferredResult();
        Map map = new HashMap();
        map.put(RET_CODE, HttpStatus.OK.value());
        map.put(RET_MSG, "查询成功.");
        map.put("username", "张三.");
        map.put("password", "123456");
        deferredResult.setResult(map);
        return deferredResult;
    }
}

User类

package com.example.bean;

/**
 * Description
 *
 * @Author : huangjinxing
 * @Email : hmm7023@gmail.com
 * @Date : 2018/10/24 11:16
 * @Version :
 */
public class User {

    private String username;
    private String password;

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    @Override
    public String toString() {
        return "User{" +
                "username='" + username + '\'' +
                ", password='" + password + '\'' +
                '}';
    }
}

启动

登陆 http://localhost:8080/swagger-ui.html#/
就可以看到有UI的 接口 
swagger的功能不止如此。

效果