Swagger使用 – 世界上最流行的api框架

为什么80%的码农都做不了架构师？>>>   

#增加依赖

compile('io.springfox:springfox-swagger2:2.6.1')
compile('io.springfox:springfox-swagger-ui:2.6.1')

#配置类

/**
 * Created by nc423 on 2017/4/5.
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    //扫描包
    @Value(value = "${swagger.api.basePackage}")
    private String basePackage;
    //标题
    @Value(value = "${swagger.api.title}")
    private String title;
    //描述
    @Value(value = "${swagger.api.description}")
    private String description;
    //联系
    @Value(value = "${swagger.api.contact}")
    private String contact;
    //版本
    @Value(value = "${swagger.api.version}")
    private String version;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))//扫描包
                .paths(PathSelectors.any())
                .build();

               // .groupName("g1")
                //.host("10.1.197.85:8080")/
                //pathMapping("/swagger"); // 在这里可以设置请求的统一前缀;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .contact(contact)
                .version(version)
                .build();
    }*/


}

#自定义json输出url

#自定义api输出url。 JSON格式  默认 /v2/api-docs
springfox.documentation.swagger.v2.path=/swagger.json

#常用注解

@ApiIgnore 忽略注解标注的类或者方法，不添加到API文档中
@Api：用在类上，说明该类的作用
@ApiOperation：用在方法上，说明方法的作用
    value api名称
    notes 备注说明
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
    name 对应方法中接收参数名称
    value 备注说明
    required 是否必须 布尔
    paramType：参数类型 body、path、query、header、form中的一种 （参数放在哪儿）
        path（用于restful接口）在url中配置{}的参数-->请求参数的获取：@PathVariable
        header-->请求参数的获取：@RequestHeader
        query-->请求参数的获取：@RequestParam,springMvc一般不需要
        body（不常用）使用@RequestBody接收数据 POST有效
        form（不常用）查看官方API文档
    dataType：参数类型
    required：参数是否必须传
    defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类
@ApiModel：描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性。例：@ApiModelProperty(dataType = "com.qualified.ReplacedWith")
@ApiParam 对单独某个参数进行说明，使用在类中或者controller方法中都可以。注解中的属性和上面列出的同名属性作用相同

#junit ###需要增加依赖

compile 'org.asciidoctor:asciidoctorj:1.5.4'
compile "io.github.swagger2markup:swagger2markup:1.3.1"
testCompile ('io.springfox:springfox-staticdocs:2.6.1')
testCompile('org.springframework.boot:spring-boot-starter-test')

import io.github.robwin.markup.builder.MarkupLanguage;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.SpringApplicationConfiguration;
import org.springframework.http.MediaType;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
import org.springframework.test.web.servlet.result.MockMvcResultMatchers;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import springfox.documentation.staticdocs.Swagger2MarkupResultHandler;
import java.io.BufferedWriter;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

/**
 * Created by nc423 on 2017/4/6.
 *
 */
@WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = SwaggerApplication.class)
public class ApiTest {

    @Autowired
    private WebApplicationContext context;

    private MockMvc mockMvc;

    @Before
    public void setUp() {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context).build();

    }

    /**
     * 生成asciidoc格式文件
     * @throws Exception
     */
    @Test
    public void convertSwaggerToAsciiDoc() throws Exception {
        this.mockMvc.perform(MockMvcRequestBuilders.get("/swagger.json")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(Swagger2MarkupResultHandler.outputDirectory("src\\docs\\asciidoc\\generated").build())
                .andExpect(MockMvcResultMatchers.status().isOk());
    }

    /**
     * 生成markdown格式文件
     * @throws Exception
     */
    @Test
    public void convertSwaggerToMarkdown() throws Exception {
        this.mockMvc.perform(MockMvcRequestBuilders.get("/swagger.json")
                .accept(MediaType.APPLICATION_JSON))
                .andDo(Swagger2MarkupResultHandler.outputDirectory("src\\docs\\asciidoc\\generated")
                        .withMarkupLanguage(MarkupLanguage.MARKDOWN).build())
                .andExpect(MockMvcResultMatchers.status().isOk());
    }

    /**
     * 生成json格式文件
     * @throws Exception
     */
    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
        String outputDir = "src\\docs\\asciidoc\\generated";  //将api-docs的json数据写入文件
        MvcResult mvcResult = this.mockMvc.perform(MockMvcRequestBuilders.get("/swagger.json")
                .accept(MediaType.APPLICATION_JSON))
                .andExpect(MockMvcResultMatchers.status().isOk())
                .andReturn();
        MockHttpServletResponse response = mvcResult.getResponse();
        String swaggerJson = response.getContentAsString();
        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }



}

转载于:https://my.oschina.net/chaon/blog/891867