swagger 常用教程

一、安装与配置

1.pom.xml 中添加相关依赖:

<!-- swagger-springmvc -->
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>com.wordnik</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.3.11</version>
        </dependency>

2.添加自定义config文件:

public class SwaggerConfig {
    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(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}
3.添加Swagger UI配置:

在GitHub上下载SwaggerUI项目,将dist下所有内容放置到  resources/static/swagger目录下

4.修改spring-mvc配置文件:

<!--  Swagger -->
	<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>
 	<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
5.修改swagger/index.html文件:
swagger默认是从http://petstore.swagger.io/v2 /swagger.json获取 API 的 JSON,这里根据个人需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情 况填写。比如我的url值为:http://localhost:8080/api-docs



二、使用方法

启动程序,访问地址:http://{ip}:{port}/{projectName}/swagger/index.htm
显示类似如下界面,则说明配置成功:

一个较全的注解demo:

@ApiImplicitParams(
    {
        @ApiImplicitParam(name = "token", dataType = "String", required = true, paramType = "query")
    }
)
@ApiOperation(value = "编辑用户信息", httpMethod = "POST", notes = "编辑用户信息")
@RequestMapping(value = "/edit", method = RequestMethod.POST)
@ResponseBody
@Authorization
public ResponseEntity<String> edit(@CurrentUser UserToken userToken,@RequestBody User user) {
    logger.info("[userToken]["+userToken+"]");
    logger.info("[user][" + user + "]");
    return new ResponseEntity<>("测试参数为对象", HttpStatus.OK);
}
对于Controller的请求参数
常见方式有两种,一种是通过方法参数的形式,另一种可以通过request对象中获取。
对于前者,swagger可以自动识别为接口参数,并生成对应接口。
而通过request方式的请求参数,无法自动识别。可以通过手动添加注解的方式予以解决:
@ApiImplicitParams(
    {
        @ApiImplicitParam(name = "token", dataType = "String", required = true, paramType = "query")
    }
)

对应的 swagger接口:


分享到:

1 条评论

昵称
  1. 匿名

    1212