swagger 与 springboot 的整合实战

说明：这篇笔记参考了下面的博客，感谢博主。

第 1 步： 引入相关的依赖。

<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>1.0.2</version>
</dependency>
<dependency>
    <groupId>org.codehaus.jackson</groupId>
    <artifactId>jackson-mapper-asl</artifactId>
    <version>1.9.13</version>
</dependency>
<dependency>
    <groupId>org.codehaus.jackson</groupId>
    <artifactId>jackson-core-asl</artifactId>
    <version>1.9.13</version>
</dependency>

附：springboot 相关代码

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.3.1.RELEASE</version>
</parent>


<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

第 2 步：在 springboot 的启动类中加入相关的代码

/** * Hello world! */
@EnableSwagger
@SpringBootApplication
public class Application {

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


    private SpringSwaggerConfig springSwaggerConfig;

    /** * Required to autowire SpringSwaggerConfig */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }


    /** * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc * framework - allowing for multiple swagger groups i.e. same code base * multiple swagger resource listings. */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(".*?");
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "李威测试使用的页面接口文档", // App Service API
                "副标题",
                "111111111111111111111111",
                "[email protected]",
                "2222222222222222222222222222",
                "3333333333333333333333333333");
        return apiInfo;
    }

}

第 3 步：在代码的控制类中加入相关的注解

@RestController
public class SampleController {


    @RequestMapping(value = "/hello")
    @ApiOperation(value = "添加用户",httpMethod ="POST", response = UserBean.class,notes = "HelloWorld")
    public UserBean hello(@ApiParam(required = true,name = "paramData",value = "用户信息 json 数据") String paramData){
        UserBean userBean = new UserBean();
        userBean.setUsername("liwei");
        userBean.setPassword("123456");
        return userBean;
    }
}

说明：
其中@ApiOperation和@ApiParam为添加的API相关注解，各参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

第 4 步：
在 GitHub 上下载 SwaggerUI
项目（https://github.com/swagger-api/swagger-ui），将dist下所有内容拷贝到本地项目webapp下面，结果目录如下图所示：
修改index.html

将index.html中

http://petstore.swagger.wordnik.com/v2/swagger.json

修改为

http://localhost:8080/{projectname}/api-docs

到此为止，所有配置完成，启动你的项目，访问

http://localhost:8086/swagger/index.html

即可看到如下所示页面：

公司内网内测项目

http://192.168.12.250:8080/swagger/

其它参考资料：
http://www.2cto.com/kf/201502/376959.html
http://blog.csdn.net/hel12he/article/details/46547863
https://cnodejs.org/topic/555c85a6e684c4c8088a0ced
http://www.ituring.com.cn/article/131792
http://fruzenshtein.com/spring-boot-swagger-ui/
http://jingyan.baidu.com/article/90bc8fc85ca182f653640cbf.html